Documentation

Prerequisites

• Windows 10 or 11 (macOS & Linux coming soon)
• 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.
3. Click Arm (or press A) to begin listening for club impact.
4. 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.

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.

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.

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

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

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
Threshold	30%	Detection sensitivity (1–100%)
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)

File Locations

Path	Contents
~/GolfSwings/settings.json	All configuration
~/GolfSwings/<timestamp>/	Session recordings
~/GolfSwings/training_data/	Audio samples for classifier
~/GolfSwings/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.
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	Decrease the threshold. Move the mic closer to the hitting area. Try pointing it at the mat.
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.