Skip to content

ForgePlayer User Guide

Feature-by-feature reference for v0.1.23-alpha. If you're brand new, start at Getting Started and come back here when you need detail.

The guide follows the app's tabs. Four have their own dedicated page; About is small enough to cover right here, in Window layout below:

  • Library — your scene browser, how tiles are matched, and opening .forge bundles.

  • Live — what's loaded, device routing, the timeline, transport, fullscreen, and calibration.

  • Setup — audio device roles, monitors, and per-monitor crop.

  • Preferences — content preference, synthesis algorithm, haptic offset, and debug mode.

Window layout

The main control window has five tabs across the top:

  • Library — your scene browser. Click a tile to activate.
  • Live — what's currently loaded, what's routing to which device, the timeline, transport, and scene-volume slider.
  • Setup — physical-device assignments (which audio device handles which role, which monitor each player goes on, and per-monitor crop
  • crop position).
  • Preferences — content preference (sound vs funscript), synthesis algorithm, haptic offset.
  • About — version, credits/attribution for the projects ForgePlayer is built on, links to docs and source, and update status (see Checking for updates below).

Top bar (right side): ⚑ Mark, Debug toggle, Export…, Clear.

Checking for updates

A few seconds after launch, ForgePlayer quietly checks forgeplayer.app for a newer release. If one's available, an "Update available" dialog offers Download (opens forgeplayer.app in your browser) or Not Now (dismisses that version's nag — a later version still prompts).

The About tab also has a manual Check for updates button with its own status line, for checking on demand — it always reports the live status regardless of any version you've dismissed.

Supported e-stim hardware

ForgePlayer drives e-stim by sending an audio signal to a stim power box. Each box plugs into its own audio output — a USB sound-card dongle (e.g. a VENTION USB sound card; any standard USB audio output works), kept separate from your speakers. You assign which dongle handles each role in Setup → Audio device roles:

  • Haptic 1 (main stim) carries the optional three-phase / stereostim signal.
  • Haptic 2 (optional) carries an optional prostate signal to a second box.

So a full e-stim setup is one or two USB audio dongles + one or two stim boxes. Match the synthesis algorithm (Settings → Generation algorithm) to your box:

Three-phase / stereostim boxes — use Pulse-based

Modern, audio-driven hardware:

Classic boxes — use Continuous

Not yet supported

  • Coyote (DG-Lab) — Bluetooth-based; Bluetooth devices haven't been tested yet.

Always Calibrate a box (Live tab) and start low before you press play — set a comfortable level on the box's own knob first.

Sessions

Top bar shows the current session name. ForgePlayer auto-saves session state (which scene is loaded, which monitors / devices are assigned) on changes. Re-opening ForgePlayer restores the last session unless you explicitly start a new one via the Library scan.

Known limitations (v0.1.23-alpha)

  • Control panel sizing on monitor change — moving the control window to a smaller secondary screen can leave it taller than 720 px. Cosmetic. Post-alpha fix.
  • Click +10 s while stopped — timeline jumps to 0 instead of staying at the seeked position. Post-alpha fix.
  • Empty Live tab when nothing is loaded — currently looks empty; hint text coming.
  • Single-decoder for video walls — currently three independent decoders synced via mpv time-pos. Frame-perfect single-decoder rendering is a future feature for true video-wall use cases.
  • macOS multi-monitor is unverified — macOS playback was rebuilt in v0.1.19-alpha on libmpv's render API, and single-display use is verified end to end on Apple Silicon. Two or more displays on a Mac has not been tested; the mirror path is exactly what it exercises, so report anything odd there.
  • HDR passthrough disabled — the HDR-on-Windows renderer (gpu-next / libplacebo) crashed on teardown, so playback uses the stable gpu renderer. HDR10 content can look over-bright on an HDR-ON display; turn Windows HDR off for now. Re-enabling awaits an upstream fix.

See BACKLOG.md (on GitHub) for the full roadmap.

Troubleshooting

A stim port is silent / reads "(unavailable — reselect in Setup)". The saved audio device was unplugged or its Windows name changed (common after a reboot or a USB re-plug). Open Setup → Audio device roles and reselect the device, then Refresh devices. ForgePlayer keeps the port silent rather than routing e-stim to your speakers. If you only have one stim box, set Haptic 2 to "— not set —".

I hear e-stim through my computer speakers. Fixed in v0.1.18-alpha — that was the release which closed it. A stim stream now opens only on a device assigned to Haptic 1 or Haptic 2, and the haptic side stays silent when neither is set, instead of falling back to the system default output (which, once displays became selectable, could be a monitor or TV). On v0.1.18-alpha or later this should not occur: check that Haptic 1 / Haptic 2 point at your USB dongle (not "Speakers"), that Scene audio is a different device, then reselect and Refresh devices — and please report it if it persists.

Sound plays but there's no picture. Largely fixed in v0.1.20-alpha — update first. If it persists, open Setup → Graphics, tick Use the default graphics adapter, and press Launch Players again.

ForgePlayer pins video to an NVIDIA GPU when it detects one, because mpv's teardown hits a confirmed, unfixed crash in AMD's D3D11 driver. Detection reads the Windows display-adapter list, which reports an NVIDIA GPU whether or not it is actually usable — and pinning the choice also removes the player's fallback to a different one. When that happens, video output never starts and audio carries on alone. The checkbox restores the fallback.

If that doesn't do it, check Setup → Playback screens: a ticked monitor that is switched off or unplugged still gets the video window, and you will never see it.

HDR video looks washed-out or over-bright. HDR passthrough is disabled for stability. Turn Windows HDR off for the playback monitor (Settings → Display → HDR) while testing.

Bluetooth output is glitchy / laggy. Bluetooth outputs are selectable and play fine for scene audio. For stim, use a wired / USB dongle: A2DP re-encodes audio with a lossy codec and for stereostim that waveform is the drive signal, plus Bluetooth latency drifts rather than holding steady.

The app disappeared mid-playback, or when closing a player. Both crashes were fixed in v0.0.16 — the second one was the crash reporter itself, which walked every live thread's stack on each of the hundreds of harmless exceptions mpv raises per session. If you still see a disappearance, grab the crash log below and file an issue; it now records only the thread that actually failed, so it's short and worth attaching.

Filing a good bug report. Turn on Debug (top bar) before reproducing, then attach:

  • ~/.forgeplayer/debug-stream-*.jsonl — the event log for that session
  • ~/.forgeplayer/faulthandler.log — native crash stacks, if it crashed

Where files live

  • Per-scene pin files — ~/.forgeplayer/pins/*.forgeplayer.json
  • Native crash log — ~/.forgeplayer/faulthandler.log
  • Library catalog index — ~/.forgeplayer/catalog.json
  • App preferences — ~/.forgeplayer/preferences.json
  • Library thumbnails (cache) — ~/.forgeplayer/thumb_cache/*.jpg
  • Session state — ~/.forgeplayer/<session-name>.session.json
  • Debug logs (when enabled) — ~/.forgeplayer/debug-stream-*.jsonl
  • Stim recordings (when env var set) — <your-chosen-dir>/stim-*.wav

Where to ask

  • Bugs / behavior issues — open an issue in the repo.
  • Architecture questions — read docs/architecture/ (on GitHub) first; that's the dev-facing set, deeper than this guide.