VLSub for OpenSubtitles.com

A modern VLC extension for downloading subtitles from OpenSubtitles.com using their latest REST API.

Note: This extension is specifically for OpenSubtitles.com (not .org) and uses their modern REST API with enhanced features and better performance.

✨ Features

• 🔍 Smart Search: Hash-based search for exact matches + name-based search with GuessIt integration
• 🌐 Multi-language Support: Select up to 3 preferred subtitle languages with intelligent prioritization
• 🎯 Auto-detection: Automatic locale detection from system settings, timezone, and IP geolocation
• 📱 Modern API: Uses OpenSubtitles.com REST API v1 for better performance and reliability
• 🔄 Auto-updates: Built-in update mechanism keeps the extension current
• 🎬 Smart Metadata: GuessIt API integration for accurate movie/TV show detection
• 🏆 Quality Indicators: Shows trusted uploaders, download counts, sync quality, and ratings
• 💾 Flexible Download: Auto-load subtitles or save manually with language codes
• 🌍 Country-specific Languages: Intelligent language suggestions based on your location

🆚 Differences from Legacy vlsub (.org version)

Feature	Legacy vlsub (.org)	VLSub OpenSubtitles.com
API	XML-RPC (legacy)	REST API v1 (modern)
Authentication	Optional	Required (free account)
Language Selection	Single language	Up to 3 languages with priority
Search Methods	Basic hash/name	Hash + Name + GuessIt fallback
Auto-updates	None	Built-in update system
Locale Detection	Simple	Advanced system detection
Quality Indicators	Basic	Detailed (trusted, HD, sync, etc.)
Performance	Slower XML parsing	Fast JSON API
Metadata	Manual input	Smart GuessIt extraction

🚀 Installation

Method 1: One-line Installation (Recommended)

macOS/Linux:

curl -sSL https://raw.githubusercontent.com/opensubtitles/vlsub-opensubtitles-com/main/scripts/install.sh | bash

Windows (PowerShell): Press Windows + R → type powershell → Enter, then run:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser; iwr -useb https://raw.githubusercontent.com/opensubtitles/vlsub-opensubtitles-com/main/scripts/install.ps1 | iex

Method 2: Arch User Repository (Arch Linux)

With paru:

paru -S vlsub-opensubtitles-com-git

With yay:

yay -S vlsub-opensubtitles-com-git

Method 3: Manual Installation

1. Download the latest vlsubcom.lua from Releases
2. Copy to your VLC extensions directory:
   • Windows: %APPDATA%\vlc\lua\extensions\
   • macOS: ~/Library/Application Support/org.videolan.vlc/lua/extensions/
   • Linux: ~/.local/share/vlc/lua/extensions/
3. Restart VLC Media Player
4. Access the extension:
   • Windows/Linux: View → VLSub OpenSubtitles.com
   • macOS: VLC → Extensions → VLSub OpenSubtitles.com (macOS puts Lua extensions under the VLC menu, not View)

📋 Requirements

• VLC Media Player 3.0 or newer
• OpenSubtitles.com account (free registration)
• Internet connection for searching and downloading
• curl command-line tool (for downloads - usually pre-installed)

🎬 Usage

Quick Start

1. Setup: Open the extension (View → VLSub OpenSubtitles.com on Windows/Linux, VLC → Extensions → VLSub OpenSubtitles.com on macOS) → Config
2. Login: Enter your OpenSubtitles.com username and password
3. Play: Start your video file
4. Search: Click "🎯 Search by Hash" for exact matches or "🔍 Search by Name"
5. Download: Click download and load automatically

Search Methods

🎯 Hash Search (Recommended)

• Best for: Local video files
• Accuracy: Finds exactly synchronized subtitles
• How it works: Calculates unique file fingerprint for perfect matching, failback to Name Search

🔍 Name Search

• Best for: Streaming content, renamed files, or when hash fails
• Features: Uses GuessIt to extract title, year, season, episode from filename
• Flexibility: Works with various naming conventions

Language Selection

• Primary Language: Your main subtitle preference
• Secondary + Third: Fallback languages shown in priority order
• Auto-detection: Extension detects your locale and suggests appropriate languages
• Country-specific: Suggests languages commonly understood in your region

Quality Indicators

• 🎯 Perfect match (moviehash sync)
• ✓ Trusted uploader
• 🎬 HD quality
• ♿ Hearing impaired
• 🤖 AI translated
• ⚙️ Machine translated

📸 Screenshots

Main Interface	Configuration	Search Results

🔧 Configuration Options

• Download Behavior: Load+Save or Manual download
• Language Codes: Add language codes to filenames (e.g., movie.en.srt)
• Tag Removal: Clean subtitle formatting tags
• Working Directory: Custom location for subtitle storage
• Auto-updates: Enable/disable automatic update checks

🌍 Supported Languages

The extension supports 100+ languages including:

• Major Languages: English, Spanish, French, German, Italian, Portuguese, Russian, Chinese, Japanese, Korean
• Regional Variants: Brazilian Portuguese, Latin Spanish, Simplified/Traditional Chinese
• European Languages: All EU languages plus Nordic, Slavic, and Baltic languages
• Global Languages: Arabic, Hindi, Hebrew, Persian, Thai, Vietnamese, and many more

Full list available in the language documentation.

🐛 Troubleshooting

Common Issues

"No results found"

• Ensure video file is local for hash search
• Try name search with manual title entry
• Check if subtitle exists on OpenSubtitles.com

"Authentication failed"

• Verify OpenSubtitles.com credentials
• Check internet connection
• Ensure account is active (not banned)

"Download failed"

• Check download quota (free accounts have daily limits)
• Verify curl is installed: curl --version
• Try again later if server is busy

Extension not visible

• Restart VLC completely
• Check file is in correct extensions directory
• Verify VLC version 3.0+

"Incompatible dkjson version" (Ubuntu / Debian)

Ubuntu and Debian ship VLC with an old bundled dkjson.luac that cannot parse floats. Upgrading VLC does not fix it — the broken file is part of the distro package (see #23).

Fix:

1. Download the latest dkjson.lua from dkolf.de/dkjson-lua.
2. Locate VLC's Lua modules directory — typically /usr/lib/x86_64-linux-gnu/vlc/lua/modules/ (Ubuntu/Debian) or /usr/lib/vlc/lua/modules/.
3. Back up the existing file: sudo cp dkjson.luac dkjson.luac.bak
4. Replace it with the downloaded file (renamed to dkjson.luac): sudo cp ~/Downloads/dkjson.lua /usr/lib/x86_64-linux-gnu/vlc/lua/modules/dkjson.luac
5. Restart VLC.

Debug Mode

Enable debug logging in VLC:

Tools → Preferences → Show settings: All → Advanced → Logger verbosity: 2 (Debug)

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/opensubtitles/vlsub-opensubtitles-com.git
cd vlsub-opensubtitles-com
# Edit vlsubcom.lua
# Test in VLC

Reporting Issues

• 🐛 Bug Reports
• 💡 Feature Requests
• 💬 Discussions

📄 License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

🙏 Acknowledgments

• OpenSubtitles.com for providing the subtitle database and API
• VideoLAN Team for VLC Media Player
• Original vlsub authors for inspiration
• GuessIt project for metadata extraction
• Community contributors for testing and feedback

💝 Support the Project

• ⭐ Star this repository to show your support
• 🐛 Report bugs to help improve the extension
• 💡 Suggest features for future releases
• 🔗 Share with other VLC users
• ☕ Support OpenSubtitles.com with a donation

📞 Support

• 📖 Documentation: docs/
• 🆘 FAQ: docs/faq.md
• 💬 Community: GitHub Discussions
• 📧 OpenSubtitles Support: Contact

---

Made with ❤️ for the VLC community
OpenSubtitles.com • VLC Media Player • GitHub