Streamlit FunPlayer
July 19, 2025 · View on GitHub
A modern React component for synchronized media and haptic playback with professional-grade performance and VR support.
Overview
FunPlayer is a versatile in-browser media player based on Video.js that synchronizes audio/video content with haptic feedback devices through the Buttplug.io ecosystem. Built with modern React architecture and optimized for real-time performance, it supports everything from simple media playback to complex multi-channel haptic orchestration.
Key Differentiators:
- 🎯 React-first architecture 100% JS/React, this Streamlit component being provided as a convenience wrapper for Python integration
- ⚡ 120Hz haptic refresh rate with optimized interpolation caching
- 🥽 Native VR support (Quest, Pico) via browser with Intiface sideload
- 🔧 Modular design - autonomous managers with event-driven communication
- 🎮 100+ device compatibility through Buttplug.io and Intiface Central ecosystem
- 🎨 Professional UI with real-time visualization and adaptive theming
Quick Start
Installation
pip install streamlit-funplayer
Basic Usage
import streamlit as st
from streamlit_funplayer import funplayer
# Simple video with haptic synchronization + custom theme
funplayer(
playlist=[{
'sources': [{'src': 'video.mp4', 'type': 'video/mp4'}],
'funscript': {'actions': [{"at": 0, "pos": 0}, {"at": 1000, "pos": 100}, ...]},
'name': 'Demo Scene'
}],
theme={
'primaryColor': '#FF6B6B',
'backgroundColor': '#1E1E1E'
}
)
Features
🎬 Universal Media Support
Formats & Protocols:
- Video: MP4, WebM, MOV, AVI, MKV, M4V
- Audio: MP3, WAV, OGG, M4A, AAC, FLAC
- Streaming: HLS (m3u8), DASH (mpd), direct URLs
- VR: 360°/180° content with WebXR integration
- Haptic-only: Timeline playback without media
Smart Playlists:
- Auto-progression with seamless transitions
- Mixed content types (video + audio + haptic-only)
- Poster generation and metadata handling
🎮 Advanced Haptic System
Device Integration:
- Buttplug.io ecosystem - 100+ supported devices
- Auto-discovery and intelligent capability mapping
- Multi-actuator support (vibration, linear, rotation, oscillation)
- Virtual device mode for development without hardware
Real-time Performance:
- 120Hz update rate with adaptive throttling
- Interpolation caching for smooth seeking
- Sub-millisecond timing accuracy for VR applications
- Memory-optimized processing for long sessions
Professional Controls:
- Per-channel configuration (scale, offset, range, invert)
- Global modulation with real-time adjustment
- Multi-channel funscripts with automatic routing
- Live visualization with customizable waveforms
🥽 VR & Cross-Platform
VR Optimization:
- Meta Quest native (via Intiface Central sideload)
- Browser-based - zero app store friction
- 90Hz display + 120Hz haptic synchronized rendering
- Memory management optimized for sustained VR sessions
Platform Support:
- Desktop: Windows, macOS, Linux
- Mobile: iOS, Android browsers
- VR Headsets: Quest 2/3/Pro, Pico, any WebXR device
- HTTPS required for device access in production
API Reference
Core Function
funplayer(
playlist: Optional[List[Dict[str, Any]]] = None,
theme: Optional[Dict[str, Any]] = None,
key: Optional[str] = None
) -> Any
Playlist Item Format
The playlist parameter is an optional list of dict items. The playlist item format follows Video.js format with additional haptic integration via the funscript parameter. Multiple sources can be provided for a single item to allow the user or the player to select the quality of the playback (480p, 720p, 1080p, etc.) depending on the bandwith available.
{
'sources': [ # Media sources (Video.js format)
{
'src': 'video_480p.mp4', # URL / Local file / BytesIO
'type': 'video/mp4', # MIME type (optional, auto-detected)
'label': '480p' # Quality label (optional)
},
{
'src': 'video_720p.mp4', # Alternate quality
'type': 'video/mp4',
'label': '720p'
}
],
'funscript': funscript, # Haptic data / URL / Local file / BytesIO
'name': str, # Display title
'description': str, # Description (optional)
'poster': str, # Poster image URL (optional)
'duration': float, # Duration in seconds (optionnal)
'textTracks': list # Subtitles/captions (optional)
}
Theme Parameters
The theme parameter accepts a dictionary with the following optional keys:
theme = {
# Colors
'primaryColor': '#FF4B4B', # Primary accent color
'backgroundColor': '#FFFFFF', # Main background
'secondaryBackgroundColor': '#F0F2F6', # Secondary background
'textColor': '#262730', # Text color
'borderColor': '#E6EBF5', # Border and divider color
# Typography & Layout
'fontFamily': '"Source Sans Pro", sans-serif', # Font family
'baseRadius': '0.5rem', # Border radius
'spacing': '1rem', # Base spacing unit
# Base theme (optional)
'base': 'dark' # Predefined theme base
}
Architecture
Design Philosophy
FunPlayer uses a modular, event-driven architecture where independent managers handle specific domains without tight coupling. FunPlayerCore serves as the central hub, coordinating between business logic managers and UI components through a unified event bus.
┌─────────────────────────────────────────────────────────────────┐
│ UI (React) │
│ FunPlayer (Main UI Component) │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ MediaPlayer │ │ HapticSettings │ │ HapticVisualizer│ │
│ │ (Video.js) │ │ (Controls) │ │ (Canvas) │ │
│ └─────────┬───────┘ └─────────┬───────┘ └─────────┬───────┘ │
│ │ │ │ │
└────────────┼───────────────────┼───────────────────┼────────────┘
│ │ │
│ │ │
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────┐
│ FunPlayerCore │
│ │
│ Event Bus + State Coordination │
│ │
│ • notify() system • Lazy manager getters │
│ • Event routing • Lifecycle management │
│ • State synchronization • Error handling │
└─────────────────────────────────────────────────────────────────┘
▲ ▲ ▲
│ │ │
│ │ │
│ │ │
┌────────────┼────────────────────┼───────────────────┼───────────┐
│ │ │ │ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ ButtPlugManager │ │FunscriptManager │ │ PlaylistManager │ │
│ │ │ │ │ │ │ │
│ │ • Device comms │ │ • Multi-channel │ │ • Content mgmt │ │
│ │ • Auto-mapping │ │ • Interpolation │ │ • Format valid │ │
│ │ • Capabilities │ │ • Channel types │ │ • Navigation │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │
│ Business Logic Managers │
└─────────────────────────────────────────────────────────────────┘
Core Components
FunPlayerCore: Central singleton orchestrating manager communication through event bus
ButtPlugManager: Device communication, capability detection, command optimization
FunscriptManager: Multi-channel parsing, intelligent interpolation, auto-mapping
PlaylistManager: Content validation, format normalization, navigation
MediaPlayer: Video.js integration with playlist extensions and VR support
System Requirements
Software Dependencies
Required:
- Python 3.9+ with pip
- Streamlit 1.45+ for component API compatibility
- Modern browser with WebSocket and WebXR support
- Intiface Central for device connectivity
Development:
- Node.js 18+ for frontend development
- npm or yarn for dependency management
Hardware Compatibility
Haptic Devices:
- 100+ devices via Buttplug.io ecosystem
- USB and Bluetooth connectivity
- Multi-actuator devices supported
- Virtual device simulation available
VR Headsets:
- Meta Quest 2/3/Pro (tested, optimized)
- Pico 4/4E, ByteDance devices
- Any WebXR-compatible headset
- Desktop VR via browser
Development
Frontend Development
The React component can be developed independently:
cd streamlit_funplayer/frontend
npm install
npm start # Development server on localhost:3001
Production Build
cd streamlit_funplayer/frontend
npm run build # Creates optimized build/
# Switch to production mode
# Edit streamlit_funplayer/__init__.py: _RELEASE = True
Testing
# Component testing
streamlit run funplayer.py
# End-to-end testing
python -m pytest e2e/
Performance Optimizations
- Interpolation caching with smart invalidation
- Throttled device commands to prevent flooding
- Memory management for long VR sessions
- Bundle optimization via Vite with tree-shaking
- Adaptive quality based on system capabilities
Use Cases
Entertainment & Content Creation
- Adult content platforms with synchronized haptic feedback
- VR experiences with enhanced tactile immersion
- Music and rhythm games with haptic enhancement
- Interactive storytelling with physical feedback
Research & Development
- Haptic perception and HCI research
- Multi-modal interface prototyping
- Therapeutic applications with controlled feedback
- Educational tools with enhanced sensory learning
Accessibility
- Haptic substitution for audio content (hearing impaired)
- Customizable intensity for different user needs
- Multi-modal feedback for enhanced accessibility
Contributing
We welcome contributions from the community! Please follow existing architectural patterns and test thoroughly with both virtual and real devices.
Focus Areas:
- Device compatibility and testing
- Performance optimizations for high-frequency updates
- Additional funscript format support
- Enhanced visualization and debugging tools
License
Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International
For commercial licensing, contact: bferrand.math@gmail.com
Acknowledgments
Built on the excellent work of:
- Buttplug.io - Universal haptic device protocol
- Intiface - Desktop bridge application
- Video.js - Robust media player framework
- Streamlit - Python web app framework
- Funscript community - Haptic scripting standards and content