Guide - Stash/HereSphere with VR and Funscript playback on Linux

howto
, , , ,
1

I’ve come across many older threads about trying to get an end-to-end setup of interactive + VR on Linux with Stash and HereSphere, most of which ended with users running into various walls. I went through this process recently and wanted to share a working setup for me, including controller rumble support. There may be some other more straightforward software for parts of this, but I wanted to stick with my current Stash/StashVR/HereSphere setup and add on some of the Interactive tools I kept seeing in other threads (that were often Windows-centric).

It’s a little bit of one-time-setup work, but fairly quick to use after. I’m by no means a Linux expert, so I can’t say how well this will work across other versions / distros, but figured if anything it might point people in the right direction. This does use Wine, so you will need to have that set up ahead of time (please see other guides online; I set it up a while ago so I can’t help much with that).

Software Needed

OS: Linux Mint / Cinnmamon - others may work fine as well

Compatibility / Tooling

Optional

  • Winetricks (WineTricks GitHub): optional; install helping/wine management
  • Python - I’m using uv (UV Homepage): optional; for Stash renaming plugin

Video / VR

Interactivity

Optional

  • Stash - RenameFile (RenameFile Readme): this or similar likely needed; helps with Funscript discovery. This one installs directly from within Stash community plugins listing.
  • Stash - Buttplug/Intiface Plugin (Stash Buttplug Readme): optional; add Intiface interactivity direct to Stash

Video Setup

Install Stash, Stash-VR, HereSphere. These are pretty hefty setup steps, but also many will likely already have these, so I’m not going to go into full setup options here.

HereSphere Setup

Launch HereSphere. In the HereSphere sidebar menu, go to User Settings. Look for Timestamp Server, and enable it. Note the IP Address (default 127.0.0.1) and Port (default 23554). There is a folder path at the bottom - you don’t actually need to worry about this and can just leave it default.

Interactivity Setup

Intiface Setup

Install the latest version of Intiface. There is a “pulled” (but still available) version from a couple days ago on Github, 3.2.0+44 – this adds controller support which is easy for testing. It was evidently causing Windows crashes, but seems to work fine in Linux.

Start Intiface, and hit the “Play” button in the upper left (optionally, in the App Modes tab, set “Start Server when Intiface Central Launches”). Under the Devices tab, click “Start Scanning” to ensure your device connects. Note: for controllers, it may need to be connected prior to launching Intiface (YMMV). Note the server address at the top - it should be ws://localhost:12345

ScriptPlayer Setup

Download the ScriptPlayer latest release on GitHub (I used Pre-Release 1.2.3.464.exe). Run the installer with Wine/Winetricks and install it. In Winetricks, also select “Install a Windows DLL or component”, and install vcrun2017. You may also just be able to download and install this directly via Wine using the link on the ScriptPlayer GitHub page (the note about also installing the Visual C Redistributables).

Launch ScriptPlayer (for me, a shortcut was added to my Mint all apps menu that directly launches it via Wine). Go to the Settings menu.

  • In the “Buttplug” section, add the Intiface websocket URL (ws://localhost:12345). Optionally, you can enable “Connect to Buttplug” to have it try to auto-start on app launch.
  • In the “Paths” section, use the + to add any folders that contain your .funscript files. Make sure you click the “*” in the entry after you add it if there are subfolders to scan.
  • In the “Player” section, go to HereSphere and add your config from above, default localhost:23554.
  • (Optional) In the “Scripts” section, change the behavior to “Clear Script” when a script can’t be loaded (a good way to make sure it’s pulling up the right scripts… you’ll get nothing if there’s any mismatches)

With HereSphere and Intiface running, we can now do an initial connection test:

  • Under the Devices menu, go to Buttplug/Intiface → Connect. You should see a message about Buttplug Connected, as well as your Device Connected.
  • Under the Video Player menu, select HereSphere. You should then see “HereSphere connected”.

If both are successful, your connections should be all set – but one final change may need to be made, so keep reading.

IMPORTANT: Funscript / File Naming

The HereSphere Timestamp Server sends along the video name to ScriptPlayer so that it can automatically load the correct script. ScriptPlayer will look at all the paths you’ve provided to find a matching funscript. This is why the folder path in HereSphere isn’t important, as ScriptPlayer will just check all the paths you told it about anyways.

However, this name may not be what your local file is named (and therefore matching funscript): it sends the name as the Stash-provided title of the video. If you’ve renamed all your files to match Stash titles, you’re good, but chances are you probably have not. Here’s how I worked through this as a one-time setup – if you’ve already got a bunch of videos/scripts, you may want to look for a bulk renaming plugin for Stash instead.

Stash Rename File plugin setup

This plugin adds a hook on to Stash title changes that will rename the underlying file, including any associated funscript. The plugin allows you to rename it to match the title, which is exactly what we want and allows ScriptPlayer to then automatically find the script.

In Stash, add the Plugin via Settings → Plugins → Available Plugins → Community Plugins. Once installed, navigate to the stash/plugins/community/renamefile folder. You will need to install the Python requirements.txt. See below if you need help on that.

Once you are done, go back to the Stash Settings → Plugins and look for RenameFile in the Plugins section at the bottom where you should now see some settings. Update “Key Fields” to just be “title”.

Note: Consider using the “dry run” setting to test it first - results will show in the plugin folder renamefile.log.

Now, in each scene in Stash that has a funscript, you will need to Edit it and trigger a re-save. By default, you can’t save without changes, but if you just put a space at the end of the description, that’s enough (and it will get trimmed on save anyways). With the file/script names now all matching the Stash video titles, the HereSphere → ScriptPlayer flow should work perfectly, syncing scripts and swapping them as new files are loaded!

Python setup for above if needed

I like a separate environment, so I installed “uv” (find in software links up top) and did the following:

  1. Install latest python via uv python install
  2. Create a new environment via uv venv - you could do this maybe in the stash base directory
  3. Activate it via source .venv/bin/activate
  4. In the renamefile folder, now you can run uv pip install -r requirements.txt
  5. In the Stash app Settings → System, update the Python Executable Path to point at the .venv/bin/python executable.

Stash Buttplug plugin (optional)

This plugin allows Stash playback in-browser to also connect to Intiface for easy interactive playback of 2D videos. Follow the plugin installation instructions on GitHub, but ignore the setup step about Settings → Interface and clicking “Connect”; that does not exist anymore, but the docs were never updated. Configuration is all done at the bottom of the Plugin section – just turn on Auto-Connect and set the Server URL to the Intiface websocket (ws://localhost:12345) and it should start playback automatically when you play a video in Stash.

Wrapping Up

I hope this guide helps someone save a few research steps. There may be a better solution for the ScriptPlayer Timestamp server connection between Intiface and HereSphere, but I kept seeing this one recommended for Windows setups, so I thought I’d give a test run with Wine, and it seems to work great.

1 Like