Documentation

Prerequisites

• Windows 10 or 11
• A USB webcam or a phone running a camera app (DroidCam, IP Webcam, EpocCam)
• A microphone (built-in laptop mic, USB mic, or phone mic via DroidCam)

Installation

1. Download the latest .exe installer from the Download section or the GitHub Releases page.
2. Run the installer — no admin privileges required.
3. Launch ReplaySwing from the Start Menu or desktop shortcut.

First Launch

1. The app auto-detects your first USB camera. If no camera is found, connect one and click Refresh Cameras in Settings.
2. Select your microphone from the Audio Device dropdown in Settings — a live level meter starts immediately so you can confirm the right mic is active.
3. Adjust the Threshold slider until normal room noise stays blue/yellow and a clap or ball strike pushes the bar into red.
4. Click Arm (or press A) to begin listening for club impact.
5. Take a swing — the app records automatically and starts looping playback.

Recordings are saved to ~/GolfSwings/ organized by session timestamp.

USB Cameras

Plug in any USB webcam and the app detects it automatically. ReplaySwing tries multiple capture backends (DSHOW → MSMF → default) so most cameras work out of the box.

For best results, use a camera that supports 720p or higher at 30 fps.

Multi-Camera Recording

Add cameras in the Settings tab. When armed, all cameras record simultaneously from a single audio trigger. Each camera saves a separate file:

• Primary: shot_0001.mp4
• Secondary: shot_0001_cam1.mp4

The live view auto-layouts cameras: 1 → full, 2 → side-by-side, 3–4 → 2×2 grid.

Per-Camera Transforms

Each camera supports individual transforms applied in real time:

Transform	Range	Description
Zoom	1.0–4.0×	Center crop with scaling
Rotation	0°–360°	Rotate by 90° steps or arbitrary angle
Flip Horizontal	On / Off	Mirror image left-right
Flip Vertical	On / Off	Mirror image top-bottom

Turn any phone into a wireless camera using a free streaming app. No extra hardware needed.

Supported Apps

App	Platform	Port	URL Format
DroidCam	Android	4747	http://<ip>:4747/mjpegfeed
IP Webcam	Android	8080	http://<ip>:8080/video
DroidCam	iOS	4747	http://<ip>:4747/video
EpocCam / Camo	iOS	—	Appears as USB camera
Custom URL	Any	—	Any MJPEG or RTSP stream

Setup Steps

1. Install the camera app on your phone and the desktop companion (if required).
2. Connect your phone and PC to the same Wi-Fi network.
3. Start streaming on the phone — note the IP address shown.
4. In ReplaySwing, go to Settings → Add Camera and enter the URL.

Tips

• DroidCam also provides a virtual microphone — useful if your PC doesn’t have a mic. The app auto-detects it and labels it “(phone mic)”.
• For the most reliable connection, use 5 GHz Wi-Fi or a USB tether.
• The app auto-reconnects if the stream drops, with exponential backoff up to 30 seconds.
• DroidCam single-client limit: DroidCam only allows one video client at a time. If another app (OBS, browser preview) is connected, close it first. ReplaySwing detects this and reports “DroidCam is busy.”

ReplaySwing listens for the distinctive sound of club impact and triggers recording automatically. Two detection modes are available.

Heuristic Classifier (Default)

Hand-tuned rules analyse 12 spectral features of each audio chunk, scoring for characteristics typical of a golf impact:

• Crest factor — high peak-to-RMS ratio (sharp transient)
• Impact ratio — concentration of energy in the 2–6 kHz band
• Rise time — fast onset (< 30 samples for strongest signal)
• Zero-crossing rate — 0.05–0.35 range typical of impacts
• Spectral centroid — 1.5–5 kHz sweet spot

A low-frequency penalty suppresses false triggers from footsteps or speech.

Learned Classifier

Once you’ve collected 10+ labeled samples, the app automatically switches to a RandomForest model trained on your specific environment. This improves accuracy for your room, club type, and mat combination.

To train: use the Mark Not Shot button to label false positives, and take real swings to accumulate positive samples. The classifier retrains automatically when enough data is available.

Live Mic Preview

Selecting a microphone from the Audio Device dropdown automatically starts a live level meter so you can instantly see which mic is picking up sound. Tap or clap near a mic to confirm it’s the right one — no need to arm the system first.

• The level bar changes colour as audio approaches the threshold: blue (quiet) → yellow (approaching) → red (above threshold — would trigger when armed).
• Adjust the Threshold slider while watching the bar to dial in the right sensitivity for your room.
• The preview stops automatically when you Arm the system (the main audio detector takes over).
• Click Stop to manually end the preview at any time.

Threshold Tuning

The sensitivity slider (1–100%) controls how confident the classifier must be before triggering. Lower values trigger more easily (more false positives); higher values are more selective.

• Default: 30%
• If you get too many false triggers, increase the threshold.
• If real swings are missed, decrease the threshold or check mic placement.

Device Persistence

Your selected microphone and threshold are saved automatically and restored when you reopen the app. The device is matched by name, so it survives reboots and USB re-plugging even if system device indices change.

Microphone Tips

• Point the mic toward the hitting area, 3–6 feet away.
• Avoid placing the mic near speakers or HVAC vents.
• A phone mic via DroidCam works well — place the phone near the tee.

Arm & Disarm

Press A or click the Arm button to start listening for triggers. While armed, the status bar shows a pulsing red indicator and "Listening for impact…"

Manual Trigger

Press T to force a recording at any time, even when armed. Useful for testing or capturing without audio (e.g., putting).

Pre-Buffer & Post-Trigger Timing

The app maintains a circular frame buffer so it can retroactively capture video from before you swung:

Setting	Default	Range	Description
Pre-trigger	1.0 s	0.5–30 s	Seconds of video kept before the trigger
Post-trigger	2.0 s	0.5–30 s	Seconds of video captured after the trigger
FPS	30	1–120	Recording frame rate

Example: With defaults, each clip is (1 + 2) × 30 = 90 frames ≈ 3 seconds.

What Happens on Trigger

1. Audio or manual trigger fires.
2. The pre-buffer (last 1 s of frames) is frozen.
3. Post-trigger frames are appended for 2 s.
4. The clip is saved as shot_NNNN.mp4 with a thumbnail.
5. Playback starts looping automatically.
6. The system stays armed for the next shot.

Looping Replay

After each shot, the captured clip loops continuously until the next trigger or until you manually pause. This lets you study your swing on repeat without touching any controls.

Speed Control

Use the speed selector or keyboard shortcuts to change playback speed:

Speed	Shortcut	Use Case
0.25×	[ to decrease	Ultra slow-mo for fine detail
0.5×		Slow motion
0.75×		Slightly slowed
1.0×		Real-time
1.5×		Quick review
2.0×	] to increase	Fast scan

Frame Stepping

Pause playback (press Space), then use ← and → to move one frame at a time. This is ideal for analysing exact positions at key moments — address, top of backswing, impact, and follow-through.

Multi-Camera View

When recording with 2+ cameras, toggle between single-camera and grid view. An angle bar lets you switch between camera perspectives (e.g., "Down-the-Line" vs "Face-On").

Overview

The PiP window is a frameless, always-on-top overlay that floats your swing replay over any application — your simulator software, launch monitor, or any full-screen app. No alt-tabbing needed.

Opening PiP

Press P or click the PiP button. The overlay appears at its last saved position (default: top-left corner, 480×270 px).

Controls

Action	How
Move	Drag anywhere on the window
Resize	Drag the window edges or corners
Zoom	Scroll wheel to zoom in (up to 5×) or out — center-crops the frame
Close	Click the × button or press P again

Behaviour

• Plays the same clip as the main window, at the same speed.
• Loops automatically alongside the main player.
• Drawing overlays (lines, circles) are rendered directly on the PiP video so annotations are always visible.
• Position and size are saved to settings and restored on next launch.
• Works with any simulator: GSPro, TGC 2019, E6 Connect, Awesome Golf, etc.

Available Tools

Tool	Shortcut	Description
Select	1	Click to select shapes, drag to move, grab handles to resize or rotate
Line	2	Draw lines for swing plane, shaft angle, or alignment analysis
Circle	3	Mark key positions — club head, ball, joints

Drawing

1. Select a tool (Line or Circle) from the Drawing tab or press 2/3.
2. Click and drag on the video frame to create the shape.
3. Use the colour picker to change the shape colour.
4. Shapes are drawn using normalised coordinates (0.0–1.0), so they scale correctly when the window resizes.

Editing Shapes

• Switch to the Select tool (1) to interact with existing shapes.
• Move: Click and drag a shape.
• Resize: Drag the endpoint handles (lines) or the radius handle (circles).
• Rotate lines: Drag the yellow rotation handle perpendicular to the line.
• Delete: Select a shape, then press Delete.
• Deselect: Press Escape to clear the selection.

Persistence

All drawing overlays are saved per-session in settings.json and restored when you reopen the app.

Overview

Compare two swings side-by-side with synchronised playback. This is invaluable for tracking improvement over time or comparing different clubs and techniques.

Opening the Comparison View

Right-click a clip thumbnail in the Gallery and choose Compare, or use the comparison button in the main window. A new dialog opens with two video players.

Controls

Control	Function
Left / Right clip selectors	Choose which clips to compare
Angle selectors	Pick camera angle per side (primary, secondary, etc.)
Play / Pause	Synchronised playback of both clips
Playback slider	Scrub both clips together
Speed selector	Adjust playback speed for both clips

Frame Offset

Swings rarely start at exactly the same moment. Use the −5 / +5 frame offset buttons on each side to fine-tune alignment — for example, sync both clips to the moment of impact.

The current offset is displayed as "Offset: X frames" for each clip.

Session Folders

Each session is stored in a timestamped folder under ~/GolfSwings/:

GolfSwings/
├── 2026-02-01_14-30-00/
│   ├── shot_0001.mp4
│   ├── shot_0001_cam1.mp4
│   ├── shot_0001.jpg          (thumbnail)
│   ├── shot_0002.mp4
│   ├── shot_0002.jpg
│   └── clips.json             (metadata)
└── 2026-02-01_16-45-00/
    └── ...

A new session folder is created automatically when the app launches. Click New Session to start a fresh folder mid-session.

Session Browser

The Sessions panel in the right sidebar lists all past sessions sorted newest-first, showing the date and shot count for each. Click any session to switch to it instantly — the gallery reloads with that session’s clips.

Configurable Save Location

By default, sessions are saved to ~/GolfSwings/. To change this, go to Settings → Save Location and click Change... to pick a new folder. A new session is started automatically at the new location.

Clip Gallery

The Gallery tab shows thumbnail previews of every clip in the current session. Click a thumbnail to load the clip for playback.

Managing Clips

Action	Description
Pin Shot	Mark a clip as a favorite — a gold star appears on the thumbnail
Share to Phone	Generate a QR code to download the clip on your phone
Delete	Remove the clip and all associated files (with confirmation dialog)
Mark Not Shot	Deletes the video but keeps the audio sample for classifier training
Open Folder	Opens the session directory in Windows Explorer

Thumbnails

Thumbnails are auto-generated from approximately one-third through each clip, giving a representative frame of the swing. They are saved as shot_NNNN.jpg alongside the video.

Pinning Clips

Right-click any clip thumbnail in the Gallery and select Pin Shot to mark it as a favorite. A gold star (★) appears on the thumbnail and in the clip label.

Using Pinned Clips

• Comparison view: When you open the Swing Comparison dialog, pinned clips are automatically pre-selected in the left and right dropdowns — no scrolling through dozens of shots.
• Quick identification: Pinned clips show a star prefix in all dropdown selectors.

Unpinning

Right-click the pinned thumbnail again and select Unpin Shot. The pin state is saved in clips.json and persists across sessions.

Overview

Share any recorded clip directly to your phone without cables, cloud uploads, or third-party apps. The app starts a temporary local web server and generates a QR code that your phone can scan to download the MP4.

How to Share

1. Right-click a clip thumbnail and select Share to Phone, or click the Share button in the playback controls.
2. A dialog appears with a QR code and the local URL.
3. Open your phone’s camera and scan the QR code (make sure your phone is on the same WiFi network).
4. The video downloads directly to your phone.
5. Close the dialog when done — the temporary server stops automatically.

Requirements

• Your phone and PC must be on the same WiFi network.
• The qrcode Python package must be installed (included in the default installer). If missing, the URL is still shown as copyable text.

Press ? at any time to show the shortcuts help dialog within the app.

Key	Action
Space	Play / Pause playback
←	Step back one frame
→	Step forward one frame
A	Toggle armed (start/stop listening for triggers)
T	Manual trigger (force a recording)
[	Decrease playback speed
]	Increase playback speed
P	Toggle Picture-in-Picture overlay
1	Select tool (drawing)
2	Line tool (drawing)
3	Circle tool (drawing)
Delete	Delete selected drawing shape
Escape	Deselect drawing / cancel mode
?	Show keyboard shortcuts help

Configuration File

All settings are stored in ~/GolfSwings/settings.json and auto-saved whenever you change a setting. The file is written atomically (temp file then rename) to prevent corruption.

Recording Settings

Option	Default	Range	Description
Pre-trigger seconds	1.0	0.5–30.0	How far back in time to capture
Post-trigger seconds	2.0	0.5–30.0	How long to keep recording after trigger
FPS	30	1–120	Recording frame rate

Audio Settings

Option	Default	Description
Audio device	System default	Microphone input to use for trigger detection (saved by name across reboots)
Threshold	30%	Detection sensitivity (1–100%). Use the live level meter to calibrate.
Sample rate	44,100 Hz	Audio sampling frequency
Chunk size	1,024	Audio buffer size

Display Settings

Option	Default	Description
PiP size	480 × 270	Picture-in-Picture window dimensions
PiP position	(100, 100)	PiP initial screen position
Thumbnail size	160 × 90	Gallery thumbnail dimensions
Window geometry	Auto	Main window position/size (auto-saved on exit)

Save Location

The Save Location setting lets you choose where all sessions, training data, and logs are stored. The default is ~/GolfSwings/. Click Change... to pick a different folder (e.g., an external drive).

File Locations

Path	Contents
~/GolfSwings/settings.json	All configuration (always in default location)
<save_location>/<timestamp>/	Session recordings
<save_location>/training_data/	Audio samples for classifier
<save_location>/logs/	Rotating log files (5 MB × 5 backups)

Camera Issues

Problem	Solution
No camera detected	Check USB connection, then click Refresh Cameras in Settings. Try a different USB port.
Black/frozen feed	Close other apps using the camera (Zoom, Teams, OBS). Restart the app.
Low frame rate	Lower the resolution in your camera’s software, or reduce the FPS setting in ReplaySwing.
Network camera won’t connect	Verify phone and PC are on the same Wi-Fi. Check the IP and port. Ensure the streaming app is running.
DroidCam connects briefly then drops	Close any other app using DroidCam (OBS, browser, DroidCam client). DroidCam only allows one video client at a time.
Network camera keeps dropping	Switch to 5 GHz Wi-Fi or use a USB tether. The app reconnects automatically with up to 30 s backoff.

Audio Issues

Problem	Solution
No audio device listed	Connect a microphone and click Refresh Devices. For DroidCam, make sure the desktop client is installed.
Too many false triggers	Increase the threshold slider. Move the mic away from speakers and fans.
Swings aren’t detected	Use the live level meter to confirm the correct mic is selected — clap near it and check the bar moves. Decrease the threshold so ball strikes push the bar into red. Move the mic closer to the hitting area.
PyAudio not installed	Audio triggering requires PyAudio. If running from source, install it with: pip install pyaudio. On Windows you may need: pip install pipwin && pipwin install pyaudio. The app still works without it — use manual trigger (T) instead.

Video & Playback Issues

Problem	Solution
Choppy playback	Reduce the playback speed or lower the recording FPS. Close resource-heavy apps.
Clip too short / too long	Adjust the pre-trigger and post-trigger times in Settings.
PiP not visible	Press P to toggle PiP. If it’s off-screen, delete the pip_position entry in settings.json and restart.
Drawings disappeared	Drawing overlays are saved per-session. Check that the correct session is loaded.

General

• Check the logs — the Log tab shows real-time messages. Log files are saved in ~/GolfSwings/logs/.
• Reset settings — delete ~/GolfSwings/settings.json to restore all defaults.
• Report a bug — use the bug report form or open an issue on GitHub.