Buttplug.io Service for Kodi

November 8, 2025 · View on GitHub

A Kodi addon that enables intimate hardware synchronization with video playback using the standardized Buttplug.io protocol. This addon automatically detects and loads funscript files to provide synchronized device control during video playback.

⚠️ Important Notice

This addon is very rudimentary and currently only supports single-axis vibrators/linear actuators. It is designed for basic funscript playback with simple devices.

If you need support for:

  • Multi-axis devices
  • Rotary actuators
  • Multiple simultaneous devices
  • Advanced funscript features
  • Other device types

Please create a feature request in GitHub Issues and I'll consider adding support based on community demand.

Features

  • Automatic Funscript Detection: Loads .funscript files matching your video names
  • Configurable Suffix Support: Choose between different funscript types (.funscript, .vib.funscript, etc.)
  • Continuous Playback: Real-time synchronization with linear interpolation between actions
  • Intiface Central Integration: Uses the standard Buttplug.io ecosystem
  • Live Settings: Change intensity, sample rate, and other settings without restarting
  • Funscript Inversion: Option to invert intensity values (0↔100)
  • Periodic Device Scanning: Optional automatic device discovery

Prerequisites

Required Software

  1. Intiface Central - Download from intiface.com
  2. Kodi (Matrix 20.0 or later)
  3. Compatible Device - Any device supported by Intiface Central

Supported Devices

This addon works with any device supported by Intiface Central, including:

  • Lovense toys
  • We-Vibe products
  • Kiiroo devices
  • Many other Bluetooth/USB intimate devices

Check IoSTIndex for device compatibility.

Installation

  1. Download the .zip file in Releases
  2. In Kodi, go to Settings, Add-ons, Install from zip file
  3. Select the file you just downloaded

Method 2: If you don't trust Releases, "build" your own

  1. Clone or download this repository
  2. Copy the script.service.buttplugio folder to your Kodi addons directory:
    • Linux: ~/.kodi/addons/
    • Windows: %APPDATA%\Kodi\addons\
    • macOS: ~/Library/Application Support/Kodi/addons/
  3. Restart Kodi

Setup & Configuration

🚨 Critical Setup Order

This order is ESSENTIAL for proper functionality:

  1. Start Intiface Central and ensure it's running on ws://127.0.0.1:12345
  2. Connect your device to Intiface Central and verify it's detected
  3. Start Kodi - the addon will automatically connect to Intiface Central

If You Start Kodi First

If you accidentally start Kodi before Intiface Central, you can reload the addon:

  1. Go to Settings > Add-ons > My add-ons > Services
  2. Click Buttplug.io Service
  3. Click Disable then Enable
  4. The addon will reconnect to Intiface Central

Addon Settings

Configure the addon in Settings > Add-ons > My add-ons > Services > Buttplug.io Service > Configure:

Connection

  • WebSocket Address: Default ws://127.0.0.1:12345 (matches Intiface Central)
  • Auto Connect on Startup: Automatically connect when Kodi starts

Device Settings

  • Scan for Devices on Startup: Scan for devices when connecting
  • Enable Periodic Device Scanning: Automatically rescan for new devices
  • Device Rescan Interval: How often to scan (seconds)
  • Device Timeout: Connection timeout (seconds)

Playback Settings

  • Sync Delay: Delay between video events and device commands (ms)
  • Intensity Multiplier: Global intensity scaling (0-200%)
  • Funscript Sample Rate: How often to sample funscript (ms, lower = smoother)
  • Invert Funscript: Reverse intensity values (0↔100)
  • Funscript Suffix: Choose funscript type (empty, "vib", "stroke", etc.)

Debug

  • Debug Logging: Enable detailed logging
  • Log Funscript Actions: Log every device command (verbose)

Usage

Funscript Files

Place funscript files alongside your videos with matching names:

Movies/
├── movie.mp4
├── movie.funscript          # Default
├── movie.vib.funscript      # Vibration-specific  
├── movie.stroke.funscript   # Stroke-specific
└── another_video.mkv
    └── another_video.funscript

Funscript Suffix Options

Use the Funscript Suffix setting to choose which files to load:

  • Empty (default): Loads video_name.funscript
  • "vib": Loads video_name.vib.funscript
  • "stroke": Loads video_name.stroke.funscript
  • Custom: Any suffix like video_name.{suffix}.funscript

Playback

  1. Start video playback - the addon automatically:

    • Detects matching funscript files
    • Loads the funscript
    • Begins synchronized device control

  2. Playback controls work normally:

    • Play/Pause: Devices start/stop accordingly
    • Seeking: Devices jump to the correct funscript position
    • Stop: Devices stop and reset

Monitoring

Check the Kodi log for addon activity:

  • Connection status to Intiface Central
  • Device discovery and connection
  • Funscript loading and playback
  • Any error messages

Troubleshooting

Common Issues

"No Intiface server running at provided address"

  • Ensure Intiface Central is running BEFORE starting Kodi
  • Check WebSocket address in addon settings matches Intiface Central
  • Try reloading the addon (disable/enable)

"No matching funscript found"

  • Ensure funscript filename exactly matches video filename
  • Check the funscript suffix setting
  • Verify the .funscript file is valid JSON

"Device not responding"

  • Ensure device is connected in Intiface Central first
  • Check device batteries and connection
  • Try rescanning for devices in Intiface Central
  • Reload the addon

Settings not showing labels

  • The addon was recently updated - restart Kodi
  • Check if language files are properly installed

Debug Mode

Enable Debug Logging and Log Funscript Actions in addon settings for detailed troubleshooting information.

Dependencies

The addon bundles these Python libraries (both included):

  • buttplug-py - Buttplug.io client library
  • websockets - WebSocket communication

Contributing

Contributions welcome! Please:

  1. Create issues for bugs and feature requests
  2. Fork and submit PRs for code contributions
  3. Test thoroughly with your devices
  4. Follow existing code style

License

MIT License - see LICENSE file for details.

Disclaimer

This addon is for adult entertainment purposes. Use responsibly:

  • Ensure device compatibility and safety
  • Follow manufacturer guidelines
  • Use at your own risk
  • Keep software updated for security

Support

Remember: This addon is rudimentary and supports only basic single-axis devices. Please request additional features through GitHub Issues if needed!