FunscriptForge
A structure-aware post-processor for funscripts. It analyzes the motion
structure of an existing script, lets you review and tag sections through an
interactive UI, and generates an improved script with smoother defaults,
expressive performance sections, and gentle breaks.
Download: latest release • Docs: liquid-releasing.github.io/funscriptforge • Community: Discord
eTransforms — Estim Character
FunscriptForge now includes an eTransforms tab — the bridge between funscript editing and estim output generation.
Pick a character for the estim output. Each one controls how sensation moves and builds over time.
| Character | What it means |
|---|
| Gentle | Soft, slow-building. Narrow arc, soft pulse onset. Good for intimate or slow content. |
| Reactive | Sharp, tracks action closely. Wide arc, instant response. Good for fast, intense content. |
| Scene Builder | Builds gradually over the scene. Circular arc, slow ramp. Rewards patience. |
| Unpredictable | Random direction changes, varied character. Keeps you guessing. |
| Balanced | Middle of everything. Good starting point for any content. |
Each character shows 1–2 contextual sliders most relevant to its personality, a live electrode path preview, and a plain-English "What you'll feel" summary.
Integration with funscript-tools
The eTransforms tab connects directly to funscript-tools. The same five characters appear in both tools — pick a character in FunscriptForge, and funscript-tools applies it to generate the alpha / beta / pulse_frequency estim outputs.
The character name is the API between all three tools: Explorer analysis → FunscriptForge transforms → funscript-tools eTransform → restim playback.
Current scope: eTransforms apply globally to the full funscript. Per-section (phrase-level) character support is the next milestone.
Features
Workflow — 9 Tabs
FunscriptForge guides you through a structured workflow. Each tab builds on the previous one:
| Tab | Purpose |
|---|
| Project | Load funscript, set output folder, add media (video/audio/captions), author info |
| Device | Select target devices (Handy, OSR2, E-Stim FOC/Stereo, Generic/Intiface), apply device awareness |
| Tone | Apply a global mood — 6 tones from Tender to Dominant, with contextual sliders |
| Phrases | Per-phrase editing with transforms, live preview, Before/After charts |
| Patterns | Batch transforms by behavioral tag across all matching phrases |
| Catalogs | Reference guide: Behavior, Structural, Replacement, Tone, Stim, and Tag catalogs |
| Stim | E-stim character selection (Gentle, Reactive, Scene Builder, Unpredictable, Balanced) |
| Export | Quality gate, transform plan, device-specific folder export |
| Next Steps | Playback guides per device, credits, license |
State flows through the chain: Original → Device → Tone → Phrases → Export
Project Tab
- Load
.funscript file, set output folder, optional media (video, audio, captions)
- Author and credits metadata
- Project summary with Accept button to initialize the pipeline
.forge project files for save/resume — pick up where you left off
Device Tab
- Select target devices: Handy, OSR2, E-Stim FOC, E-Stim Stereo, Generic/Intiface
- Device limits table shows combined constraints and which device is the bottleneck
- Minimum-fix algorithm: analyzes violations, clamps only what exceeds limits, preserves the rest
- Side-by-side preview: Original vs Device Aware, plus full-width result chart with stats
- Intensity spikes slider for estim: None / Rare / Moderate / Frequent — allows occasional full-range cycles
- Everything downstream (Tone, Phrases) works on the device-aware baseline
Tone Tab
- 6 tones ordered by intensity: Tender → Build → Tease → Edge → Climax → Dominant
- Dual suggestions: "Best match" and "Most variety" based on funscript analysis
- Variable slider count per tone (2–4 contextual sliders from sensitivity matrix)
- Impact slider (0–1) scales the overall tone effect
- Before/After preview reads from the device-aware chain
- Credit to Edger's Funscript-Tools
Analysis
- Structural analysis: phases → cycles → patterns → phrases → BPM transitions
- Behavioral classification into 10 tags (stingy, giggle, plateau, drift, half-stroke, drone, lazy, frantic, ramp, ambient)
- Duration-based phrase splitting for uniform-tempo funscripts
- Real-time progress indicator shows each pipeline stage as it runs
- Cross-funscript pattern catalog — accumulates stats across all analysed files
Phrase Editor
- Full-funscript colour-coded chart with white phrase bounding boxes; click any phrase to edit
- Tone category first in transform picker — all 6 tones available per-phrase with Impact slider
- Behavior, Structural, and Plugin categories follow
- Auto-accept workflow: Prev/Next/Done navigation auto-accepts the current transform
- Cancel reverts all changes for the phrase to entry state
- Phrases Accept button saves all edits to chain with green guidance for next steps
- Cycle-based phrase split and Concat with Next Phrase
- Large-file phrase highlight — selected phrase renders with full velocity colour over grey background
Pattern Editor
- Select phrases by behavioral tag; view all matching instances at once
- Per-instance transform + per-segment split with independent transforms per sub-range
- "Suggested transform" shown per tag; Apply to all copies to every matching instance
- Selector chart reflects accepted transforms in real time
Audio / Video Player
- Phrase-restricted HTML5 player — plays only the currently selected phrase window
- Animated red playhead overlaid on the waveform chart; Back 5 s / Forward 5 s controls
- Set split here — click during playback to send timestamp to Pattern Editor as a split point
- Local mode: media streams from disk at full quality (no upload, no size limit)
- Magic-byte validation on 9 supported types (MP3, MP4, M4A, MOV, WAV, OGG, WebM, MKV, AAC)
Catalogs Tab
Six catalog sections in one reference tab:
- Behavior — amplitude shaping, position adjustment, smoothing, break/recovery, performance, rhythmic patterns
- Structural / Tempo — tempo reduction transforms
- Replacement — generated shapes (stroke, drift, tide)
- Tone Catalog — all 6 tones with intensity levels, slider descriptions, summary table
- Stim Catalog — all 5 e-stim characters with path shapes, slider descriptions, summary table
- Tag Catalog — all 10 behavioral tags with characteristics, suggested transforms, before/after charts
Each entry includes live interactive sliders and preview charts.
Export
- Device-specific folder export (e.g.
output/handy/, output/estim-foc/)
- Before/After overlay — toggle to see what transforms changed
- Quality gate — velocity and short-interval checks; pass/fail badge
- Export log —
_forge_log key records every transform for reproducibility
- Media copy — input video/audio/captions copied to output folder
- Open folder button (platform-native file explorer)
Undo / Redo
- 50-level undo/redo stack for accepted transforms
- Keyboard shortcuts:
Ctrl+Z undo, Ctrl+Y / Ctrl+Shift+Z redo, Ctrl+S save
- Sidebar ↩ Undo / ↪ Redo buttons with operation-label tooltips
Privacy
- Runs entirely on your machine — no account, no cloud sync, no telemetry
- Your funscripts, media files, and edits never leave your computer
Accessibility
- WCAG 2.1 Level AA — all Critical items and five of seven Major items resolved
- Keyboard shortcut support throughout; screen-reader labels on all interactive elements
CLI
assess, transform, customize, pipeline — full analysis and transform pipelinephrase-transform — apply any catalog transform to individual phrases from the command linefinalize — blend seams + final smooth as standalone post-processingexport-plan — mirror of the UI Export tab; supports --apply to write output directlycatalog — query and manage the cross-funscript pattern catalogvalidate-plugins — validate JSON recipe files and report Python plugin gate status without starting the appmeta — auto-derive pace, intensity, arc, mood, Hub tags, and tone suggestion from a funscriptsuggest-tone — print the auto-suggested Tone label and rationalebeats — extract beat timestamps from a video file; writes _beats.json + _beats.csvparse-captions — parse SRT or WebVTT captions; writes _captions.jsontest — run all tests
User workflow
1 — Analyze
The analyzer reads a .funscript file and detects its motion structure,
working through five stages:
actions → phases → cycles → patterns → phrases → BPM transitions
- Phases — individual up, down, or flat direction segments
- Cycles — one complete oscillation (one up + one down phase)
- Patterns — cycles with the same direction sequence and similar duration
- Phrases — consecutive runs of the same pattern, each with a BPM value
- BPM transitions — points where tempo changes significantly between phrases
The output is a single JSON file capturing the full structural picture.
2 — Review in the UI
Open the FunscriptForge desktop app (Tauri + React) and load your funscript. The
Analyze view shows the full pipeline output — a colour-coded phrase timeline,
BPM transitions table, and drill-down detail for patterns and phases.
The Phrase Editor tab shows the full funscript as a colour-coded chart
with phrase bounding boxes. Click any phrase to open its detail panel where
you can select a transform, tune its parameters with live sliders, and see a
Before / After preview. Use Apply to all to copy the same transform to
every instance of the same behavioral tag.
The Pattern Editor tab lets you fix behavioral issues phrase by phrase.
Each phrase instance shows an original chart and a live preview as you adjust
transforms. For phrases that span a long section (e.g. a single pattern
covering most of the file), you can split the phrase into non-overlapping
sub-ranges and apply a different transform to each one. Split boundaries
are shown as dashed lines on both charts. Use Apply to all to copy the
split structure — scaled proportionally — to every other instance of the same
behavioral tag.
The Catalogs tab has six sections:
- Behavior — transforms that reshape amplitude, position, smoothing, rhythm
- Structural / Tempo — tempo reduction transforms
- Replacement — generated shapes (stroke, drift, tide)
- Tone Catalog — all 6 tones with intensity, sliders, summary table
- Stim Catalog — all 5 e-stim characters with path shapes, sliders, summary table
- Tag Catalog — all 10 behavioral tags with characteristics, suggested transforms, before/after charts
3 — Export
The Export tab aggregates every transform applied across the workflow.
Device-specific folders are created automatically (e.g. output/handy/, output/estim-foc/).
Tag-aware auto-suggestions (suggest_transform, checked in priority order):
| Tag | Suggested transform | Notes |
|---|
frantic | halve_tempo | BPM > 200 |
giggle, plateau, lazy | amplitude_scale | Amplify; scale computed to target peak hi ≈ 65 |
stingy | amplitude_scale | Reduce; scale computed to target peak hi ≈ 65 |
drift, half_stroke | recenter | target_center = 50 |
drone | beat_accent | Adds rhythmic variation |
ramp | funnel | Progressive center shift + amplitude scaling for energy arc shaping |
ambient | waiting | Low BPM + shallow amplitude + long duration |
Post-processing: blend seams (bilateral LPF at style boundaries) and final smooth (light global LPF).
4 — Transform and customize
After reviewing in the UI, run the full pipeline to produce the final funscript.
Option A — in the app (Export tab)
Open the Export tab and run the full pipeline. Adjust the BPM threshold and
amplitude scale, toggle whether to apply your Work Item windows, then write the result.
This produces a _pipeline.funscript file with an embedded _forge_log, independent of
any phrase-editor transforms.
Option B — command line
# Step 1 — analyze (or use the UI; it saves a cached JSON automatically)
python cli.py assess input.funscript --output output/assessment.json
# Step 2 — transform (BPM-threshold baseline)
python cli.py transform input.funscript \
--assessment output/assessment.json \
--output output/transformed.funscript
# Step 3 — customize (apply your tagged windows)
python cli.py customize output/transformed.funscript \
--assessment output/assessment.json \
--perf output/input.performance.json \
--break output/input.break.json \
--raw output/input.raw.json \
--output output/final.funscript
# Or run both steps at once
python cli.py pipeline input.funscript --output-dir output/
System requirements
Privacy first. FunscriptForge runs entirely on your machine.
Your funscripts, media files, and edits never leave your computer — no account,
no cloud sync, no telemetry.
FunscriptForge is a native Tauri 2 + React desktop app. The packaged Windows
installer bundles everything it needs (the forge-cli Python backend and a static
ffmpeg); there is no separate Python, pip, or browser install.
Minimum
| Windows |
|---|
| OS | Windows 10 64-bit (build 1903+) / Windows 11 |
| CPU | Any 64-bit dual-core x86 |
| RAM | 4 GB |
| Free disk | ~1 GB (app + bundled backend & ffmpeg) |
| Runtime | WebView2 (preinstalled on Windows 11; installer fetches it if missing) |
| Display | 1920 × 1080 (1080p) minimum |
Windows-first. v0.1.0-alpha ships a Windows installer. macOS and Linux
builds are a post-beta follow-up — until then, run from source on those platforms.
Recommended (production funscripts)
| Resource | Recommendation | Why |
|---|
| RAM | 8 GB+ | Long funscripts (1+ hour) load the full action list into memory |
| CPU | 4-core, 3 GHz+ | Analysis runs single-threaded; faster clock speed = faster analysis |
| Free disk | 10 GB+ | Media files stay on disk during editing and are never modified — allow room for originals plus exports |
| Display | 2560 × 1440 (QHD) or larger | The Phrase and Polish tabs use a 3-pane layout with an embedded media player; QHD provides enough vertical space without scrolling |
Internet connection
An internet connection is only required once, to download the installer.
After that the app runs completely offline — no calls home, no background updates.
Getting started
Install (packaged app)
Download the latest Windows installer (.msi or .exe / NSIS) from the
releases page
and run it. See docs/INSTALL.md for details.
Run from source (developers / macOS / Linux)
FunscriptForge is a Tauri 2 + React app in ui/web/, driving the repo-root
Python backend (cli.py). You need the sibling repos checked out next to this one
(funscript-tools, forge-ui-components, videoflow, forgemoment).
# 1. Python backend env
python -m venv .venv
.venv/Scripts/activate # Windows (use source .venv/bin/activate elsewhere)
pip install -r requirements.txt
# 2. Frontend + full desktop app (from ui/web/)
cd ui/web
npm install
npm run tauri:dev # Rust shell + React + Python backend
# Production installers:
npx tauri build # → src-tauri/target/release/bundle/
In development the Rust shell invokes the backend through the .venv
(python cli.py <command>), with ffmpeg / ffprobe resolved on PATH. See
ui/web/README.md for prerequisites and the platform adapter.
Analyze from the command line
python cli.py assess path/to/file.funscript --output output/assessment.json
Demo resources
Big Buck Bunny (Blender Foundation, 2008) is a recommended safe-for-work test video for
trying the audio/video player feature. Community funscript sites carry demo scripts that pair
with it, making it easy to exercise the Phrase Editor, Pattern Editor, and media player without
needing private content.
The Blender Foundation released the video under the
Creative Commons Attribution 2.5 license,
so you can use, modify, and share it freely as long as you credit the creators.
© 2008 Blender Foundation | www.bigbuckbunny.org
Project structure
funscriptforge/
├── assessment/ # Step 1: structural analysis + behavioral classification
│ ├── analyzer.py # FunscriptAnalyzer
│ ├── classifier.py # BehavioralTag, TAGS registry, annotate_phrases
│ └── readme.md
├── catalog/ # Cross-funscript pattern catalog
│ └── pattern_catalog.py # PatternCatalog (persistent JSON)
├── pattern_catalog/ # Step 2: BPM-threshold baseline transform
│ ├── transformer.py # FunscriptTransformer
│ ├── phrase_transforms.py # TRANSFORM_CATALOG (22 named transforms incl. funnel)
│ └── config.py # TransformerConfig
├── user_customization/ # Step 3: window-based fine-tuning
│ ├── customizer.py # WindowCustomizer
│ └── config.py # CustomizerConfig
├── visualizations/ # Plotly + matplotlib motion chart components
├── ui/ # UI code
│ ├── common/ # Framework-agnostic models and logic
│ │ ├── work_items.py # WorkItem + ItemType
│ │ ├── project.py # Project state
│ │ ├── pipeline.py # run_pipeline / run_pipeline_in_memory
│ │ └── tests/
│ └── web/ # Tauri 2 + React + Vite desktop app
│ ├── src/ # React source (App.jsx, api/forge.js, tabs)
│ └── src-tauri/ # Rust shell (commands.rs bridges to cli.py)
├── forge/ # Forge-layer modules (project, metadata, media analysis)
│ ├── metadata.py # derive_metadata() — auto-derive pace/intensity/arc/mood/tags/tone
│ ├── beats.py # extract_beats() — PyAV + librosa beat detection
│ ├── captions.py # parse_captions() — SRT + WebVTT parser
│ └── video.py # video_stats(), analyze_motion()
├── cli.py # Python backend / CLI (frozen to forge-cli for distribution)
├── forge-cli.spec # PyInstaller spec — freezes cli.py + scientific stack
├── docs/ # MkDocs user documentation site (in progress)
├── internal/ # Internal planning docs (gap analysis, backlogs, build notes)
├── media/ # App images, logos, icons
├── tests/ # Core pipeline unit tests
├── models.py # Shared dataclasses (Phrase now carries tags + metrics)
├── utils.py # Timestamp helpers, low-pass filter, writable_base_dir
└── requirements.txt
CLI reference
# Assess
python cli.py assess <funscript> [--output <path>] [--config <json>]
[--min-phrase-duration SECONDS] [--amplitude-tolerance FRACTION]
# Transform (BPM-threshold baseline)
python cli.py transform <funscript> --assessment <path>
[--output <path>] [--config <json>]
# Customize (window-based fine-tuning)
python cli.py customize <funscript> --assessment <path>
[--output <path>] [--config <json>]
[--perf <json>] [--break <json>] [--raw <json>] [--beats <json>]
# Full pipeline (assess → transform → customize in one step)
python cli.py pipeline <funscript> --output-dir <dir>
[--perf <json>] [--break <json>] [--raw <json>] [--beats <json>]
[--transformer-config <json>] [--customizer-config <json>]
# Phrase-level transform (applies a catalog transform to individual phrases)
python cli.py phrase-transform <funscript> --assessment <path>
--transform smooth --phrase 3 [--param strength=0.25]
--transform normalize --all
--suggest [--bpm-threshold 120] # tag-aware auto-pick
[--output <path>] [--dry-run]
# Finalize (blend seams + final smooth as post-processing)
python cli.py finalize <funscript> [--output <path>]
[--param seam_max_velocity=0.3] [--param smooth_strength=0.05]
[--skip-seams] [--skip-smooth]
# Export plan (mirror of the UI Export tab)
python cli.py export-plan <funscript> [--assessment <path>]
[--transforms overrides.json] [--no-recommended]
[--bpm-threshold BPM] [--format table|json]
[--apply] [--output <path>] [--dry-run]
# Catalog
python cli.py catalog [--catalog <path>] [--tag TAG] [--remove FUNSCRIPT] [--clear]
# Validate user-transform plugins (JSON schema check + Python plugin gate status)
python cli.py validate-plugins [--verbose] [--recipes-dir <path>] [--plugins-dir <path>]
# Auto-derive metadata (pace, intensity, arc, mood, Hub tags, tone suggestion)
python cli.py meta <funscript> [--assessment <path>] [--output <json>] [--format table|json]
# Print tone label + rationale only
python cli.py suggest-tone <funscript>
# Extract beat timestamps from video (requires: pip install av librosa)
python cli.py beats <video> [--audio <override>] [--output-dir <dir>]
# Writes: _beats.json, _beats.csv
# Parse SRT or WebVTT captions
python cli.py parse-captions <file.srt|.vtt> [--output-dir <dir>] [--print]
# Writes: _captions.json
# Utilities
python cli.py visualize <funscript> --assessment <path> [--output <path>]
python cli.py config [--customizer] [--analyzer] [--output <path>]
python cli.py test
Running tests
# Python backend: core pipeline + integration + engine tests
python -m unittest discover -s tests -v
# Python UI-common layer
python -m unittest discover -s ui/common/tests -v
# All Python tests at once
python cli.py test
# React frontend tests
cd ui/web && npm test
Documentation
| README | Description |
|---|
| assessment/readme.md | Structural analysis pipeline — phases, cycles, patterns, phrases, BPM transitions (Step 1) |
| pattern_catalog/README.md | BPM-threshold baseline transformer (Step 2) |
| pattern_catalog/EXTENDING_TRANSFORMS.md | Adding custom transforms via JSON recipes or Python plugins; security model |
| user_customization/README.md | Window-based fine-tuning customizer (Step 3) |
| ui/README.md | Frontend overview — the Tauri + React desktop app, backend, distribution |
| ui/web/README.md | Tauri + React app — prerequisites, run modes, forge.js adapter, tab flow |
| ui/common/README.md | Framework-agnostic business logic: Project, WorkItem |
| user_transforms/README.md | Adding custom transforms via JSON recipe files |
| plugins/README.md | Adding custom transforms via Python plugins |
|
© 2026 Liquid Releasing. Licensed under the MIT License. Written by human and Claude AI (Claude Sonnet).
FunscriptForge™ is a trademark of Liquid Releasing.
The .funscript file format is a community standard not owned by Liquid Releasing.
