🎬 Vavoo Stream Live
## 📌 Overview
Vavoo Stream Live Plugin is an Enigma2 extension that provides access to thousands of live TV channels from multiple countries. It features a built-in local proxy for improved reliability, automatic bouquet updates, EPG integration, real-time notifications, satellite priority matching, and seamless integration with your Enigma2 receiver.
## 🖼️ Screenshots
| 
|
## ✨ Key Features
- **Live TV Streaming** – Watch live channels from various countries
- **Country & Category Browsing** – Organized by country and category
- **Search Functionality** – Find channels by name in real-time
- **Enigma2 Bouquet Export** – Export channels directly to your channel list
- **M3U Playlist Generation** – Create standard M3U playlists for external players
- **EPG Integration** – Electronic Program Guide for supported channels, served via GitHub
- **Satellite Priority Matching** – Intelligent EPG matching prioritizing user-configured satellites
- **Automatic Updates** – Scheduled bouquet updates to keep channels current
- **Local Proxy Integration** – Enhanced reliability and no 10-minute blocks
- **Multi-Language Support** – Including right-to-left language support
- **Customizable Interface** – Change backgrounds, fonts, and settings
- **Proxy Status Monitor** – Real-time proxy status display in main interface
- **Real-time Notifications** – Visual feedback for all operations (exports, EPG processing, errors)
- **Complete EPG Cache** – Persistent storage with matched/unmatched status and Rytec IDs
- **Thread-safe Operations** – Background exports with progress notifications
- **Text Key Functions** – Manual proxy refresh using TEXT button
- **Cache Format Fix** – Yellow button to clean up and fix cache format
- **HTTP 451 Handling** – Automatic fallback to mirror sites when primary is blocked
## 🔔 Notification System
The plugin includes a sophisticated notification system that provides real-time feedback:
- **Welcome Message** – Shown when the plugin starts
- **Export Progress** – "Export started", "Bouquet ready", "EPG processing completed"
- **Error Alerts** – Clear error messages with details
- **Cache Operations** – Notifications during cache format fixes
- **Thread-safe** – Notifications work from any background thread
- **Message Queue** – Messages are queued if the UI isn't ready
- **Singleton Pattern** – Single notification manager instance across all plugin screens
### Notification Types
| Type | Duration | Color | Example |
|------|----------|-------|---------|
| Info | 3 seconds | Blue | "Export started. Bouquet will be available shortly." |
| Success | 4 seconds | Green | "EPG processing completed for 25 channels" |
| Warning | 4 seconds | Yellow | "An export for another country is already in progress" |
| Error | 5 seconds | Red | "Bouquet creation error: connection timeout" |
## 🚀 Quick Start Guide
### First-Time Setup
1. **Open the Vavoo Plugin** – The proxy will start automatically (welcome notification appears)
2. **Select a Country** – Choose your desired country (e.g., "Italy")
3. **Press GREEN Button** – Export favorites to Enigma2 bouquets (notifications show progress)
4. **Return to TV** – Your channels will appear in the channel list!
### Automatic Updates (Recommended)
- Go to **Menu Config** → Enable **"Scheduled Bouquet Update: ON"**
- Choose update interval (5-3600 minutes, in 5-minute steps) or fixed time
- The proxy will handle everything automatically
### EPG Setup
- Enable **"Enable Vavoo EPG"** in the configuration menu
- The plugin generates country-specific EPG files in `/etc/epgimport/`
- EPG data is fetched from GitHub and displayed in the player overlay (press OK)
### Cache Maintenance
- Press **YELLOW button** in the main menu to fix cache format
- This will add missing fields and remove duplicate entries
- A notification will show the result
## 🔧 User Configuration
In the Config Menu:
- ✅ **Scheduled Bouquet Update**: ON/OFF (only required setting)
- ✅ If ON: Choose interval (5-3600 min) or fixed time
- ✅ **Enable Vavoo EPG**: Generate EPG sources for EPGImport
- ✅ **Proxy Enabled**: Enable/disable the local proxy (default: ON)
- ✅ **List Position**: Place Vavoo bouquets at top or bottom of channel list
- ✅ **Select Background**: Choose custom background images
- ✅ **Link in Main Menu**: Show plugin in main Enigma2 menu
- ✅ **Send Anonymous Statistics**: Opt in/out of anonymous startup/heartbeat pings (default: ON)
- Proxy and updates are managed automatically
## 🎯 Benefits
- ✅ **No 10-minute blocks** – Proxy handles authentication tokens
- ✅ **Automatic updates** – Keep bouquets fresh without manual work
- ✅ **Improved performance** – Local proxy provides stable streams
- ✅ **EPG support** – Program guide for many channels with satellite priority
- ✅ **Clean system** – Single configuration point
- ✅ **No manual refreshes** – Everything happens automatically
- ✅ **Real-time monitoring** – Proxy status always visible
- ✅ **Visual feedback** – Notifications for all operations
- ✅ **Manual control** – Force proxy refresh with TEXT button
- ✅ **Cache management** – Fix cache format with YELLOW button
## 🛠 Technical Features
### Local Proxy (127.0.0.1:4323)
- Manages authentication with Vavoo servers
- Automatically renews tokens every 8-9 minutes (TOKEN_ADDON_SIG = 600 seconds)
- Provides stable URLs for bouquets
- Completely eliminates 10-minute streaming blocks
- Self-monitoring with automatic restart on failure
- Connection pool management to prevent timeouts
- **Mirror Support**: Automatic fallback between vavoo.to and kool.to when HTTP 451 is detected
- **Token Monitor**: Background thread that checks token age every 60 seconds
- **Active Stream Tracking**: Notifies proxy when streams start/end for better resource management
### EPG Integration & Satellite Priority Matching
- EPG data is generated per country and stored in `/etc/epgimport/vavoo_.channels.xml`
- A master source file (`vavoo.sources.xml`) is created for EPGImport
- The player fetches EPG via the proxy redirect to GitHub raw files
- **Intelligent Channel Matching** (in priority order):
- Local per-box cache, then a downloaded Rytec-based temp cache
- **Curated EPG channel database** (`epg-channel-db/vavoo_channels_.json`,
fetched and cached in-memory for 24h): a pre-solved
channel-name → EPG-feed-id mapping, generated offline per country
by matching Vavoo's own live channel list against that country's
own `epg_.xml` feed directly - built specifically for
countries Rytec covers poorly (e.g. Spain, Poland, Turkey)
- Live Rytec fuzzy matching, then a live feed-direct fallback
- Every matched channel gets a synthetic, per-channel-unique service
reference (not a shared Rytec tuple) so unrelated channels across
different countries can never collide in Enigma2's EPG cache, even
when they share the exact same EPG id
- Scans user-configured satellites from Enigma2 NimManager
- Prioritizes matches from satellites the user actually has configured
- Falls back to Italian satellites (13°E HotBird, 5°W Eutelsat) for Italian channels
- Priority levels: Satellite > Terrestrial > Cable > IPTV
- **Boost multipliers**: 1.5× for user-configured satellites, 1.3× for Italian satellites
### Notification System Architecture
- **Singleton Pattern**: Single manager instance across all screens
- **Thread-safe**: Lock mechanism prevents race conditions
- **Message Queue**: Pending messages stored until UI is ready
- **Auto-cleanup**: Notifications automatically hide after timeout
- **Fallback**: Console logging when UI not available
## 📋 API Endpoints
The proxy provides these endpoints:
- `/status` – Check proxy status
- `/channels?country=CountryName` – Get channels by country
- `/vavoo?channel=ChannelID` – Resolve stream URLs (302 redirect)
- `/stream?ref=ServiceReference` – Resolve by Enigma2 service reference (via `vavoo_sref_map.json`) and proxy the stream content directly
- `/catalog` – Full channel catalog
- `/countries` – List all countries
- `/refresh_token` – Force token refresh
- `/epg/.xml` – Redirect to GitHub EPG file
- `/health` – Detailed health check with token age
- `/shutdown` – Gracefully stop proxy
## 🗂 File Management
### Bouquet Export
- Path: Plugin menu → Select country → GREEN button
- Creates bouquets with proxy URLs: `http://127.0.0.1:4323/vavoo?channel=CHANNEL_ID`
- Service references are matched against the curated EPG channel database and the Rytec database for EPG compatibility (see "EPG Integration & Satellite Priority Matching" above)
- EPG mapping files are automatically generated for each country
- Supports both flat bouquets and hierarchical categories
### M3U Export
- Path: Config Menu → "Generate .m3u files"
- Downloads playlist from proxy and saves as `vavoo_[country]_playlist.m3u`
- Supports single country or all countries export
### EPG Files
- Location: `/etc/epgimport/vavoo_*.channels.xml`
- Generated locally on the box at export time (`write_epg_mapping_file()`), not by any GitHub Action
- Programme data source: `https://raw.githubusercontent.com/Belfagor2005/vavoo-player/master/epg_.xml`
### Curated EPG Channel Database
- Location: `epg-channel-db/vavoo_channels_.json` in this repo, fetched by the plugin at match time and cached in-memory for 24h
- A `vavoo_channels_.review.json` file is generated alongside each one for names that need a human to resolve - never read by the running plugin
- Regenerated by `generate_epg_channel_db.py` (dev-time script, run against a live `vavoo_proxy` instance) - the GitHub Actions workflow `generate_epg_channel_db.yml` runs this weekly (plus on-demand) on a self-hosted runner and commits the result back
### Cache Files
- **EPG Cache**: `/etc/enigma2/vavoo_epg_cache.json` – Persistent cache of matched channels with Rytec IDs
```json
{
"channel_name_country": {
"id": "rytec_id",
"sref": "4097:0:1:1773:60E1:217C:5A0000:0:0:0:",
"name": "channel_name",
"country": "it",
"matched": true,
"timestamp": "2026-03-19 10:23:15"
}
}
```
- **Unmatched Cache**: `/etc/enigma2/vavoo_epg_unmatched_cache.json` – Stores channels that couldn't be matched
```json
{
"channel_name_country": {
"id": "channel_name_country",
"name": "channel_name",
"country": "it",
"sref": "4097:0:0:0:0:0:0:0:0:0:",
"timestamp": "2026-03-19 10:23:15",
"matched": false,
"attempts": 3
}
}
```
Features:
- Tracks matching attempts count
- Auto-converts old format entries
- Persistent across plugin restarts
- Used for future matching improvements
- **SREF Map**: `/etc/enigma2/vavoo_sref_map.json` – Maps service references to channel IDs for the proxy
- **Curated Channel DB Cache** (in-memory only, not a file on disk): each country's downloaded `epg-channel-db/vavoo_channels_.json` is kept in memory for 24h per process so repeated exports/lookups don't re-download it every time - cleared on plugin/proxy restart
## 🚨 Troubleshooting
### Quick Diagnostics
```bash
# Check proxy status
curl -s http://127.0.0.1:4323/status
# Check proxy logs
cat /tmp/vavoo_proxy.log
# Check plugin logs
cat /tmp/vavoo.log
# Check EPG cache
cat /etc/enigma2/vavoo_epg_cache.json
# Check unmatched cache
cat /etc/enigma2/vavoo_epg_unmatched_cache.json
# Check proxy health
curl -s http://127.0.0.1:4323/health
```
### Common Issues
| Problem | Solution |
|---------|----------|
| "No channels found" | Restart plugin, check internet connection |
| Bouquets don't open | Ensure proxy is running (check with curl) |
| Stream doesn't start | Proxy should auto-refresh tokens |
| M3U export fails | Verify port 4323 is accessible |
| "No programme found" | Clear EPG cache and re-export bouquet; check country EPG file exists |
| EPG not updating | Verify EPG is enabled in config and GitHub files are accessible |
| HTTP 451 errors | Proxy automatically switches to mirror sites (kool.to) |
| Duplicate cache entries | Press YELLOW button in main menu to fix cache format |
### Notification Issues
| Problem | Solution |
|---------|----------|
| Only first notification shows | Ensure `init_notification_system(session)` is called once in `MainVavoo` |
| Notifications from background don't appear | The singleton manager now handles this automatically |
| Message appears truncated | Check Python 2/3 encoding in notification text |
| Notifications too fast/slow | Adjust duration parameter in `quick_notify(message, seconds)` |
### Cache Issues
| Problem | Solution |
|---------|----------|
| Unmatched channels not saving | Check write permissions to `/etc/enigma2/` |
| Duplicate unmatched entries | Press YELLOW button or run `fix_cache_format(remove_duplicates=True)` |
| Cache file corrupted | Delete the file and restart - it will be regenerated |
| Old format entries | The plugin auto-converts them on read or use YELLOW button |
## Privacy & Anonymous Stats
Vavoo sends **anonymous** startup notifications to help improve the plugin.
**Collected (anonymous only):**
- Temporary session ID (changes on every reboot)
- Plugin version
- Event type (startup/heartbeat)
- Timestamp
**Not collected:** IP, MAC, personal data, channels, or any identifying info.
**Disable:** Config menu → "Send Anonymous Statistics" → No
[View source code](https://github.com/OwnerPlugins/vavoo/blob/main/usr/lib/enigma2/python/Plugins/Extensions/vavoo/vavoo_stats.py)
## 📝 Important Notes
- **Notifications are thread-safe** – You can call `quick_notify()` from any background thread
- **Message queue system** ensures no notifications are lost during plugin startup
- **Unmatched channels are persistent** – They survive plugin restarts and are used for future matching attempts
- **Attempts counter** helps track how many times a channel has been processed
- **EPG cache now includes matched/unmatched status** – Each entry has a `matched: true/false` flag
- **Satellite priority** – The plugin reads your Enigma2 satellite configuration and prioritizes those channels
- Old bouquets won't work with new system – re-export required
- Proxy runs in background – bouquets work even after closing plugin
- Minimal memory usage (~20-50MB)
- Use **TEXT button** in main menu to manually refresh proxy token
- Use **YELLOW button** to fix cache format
- Proxy status is displayed in real-time in the main interface
## 🤝 Credits
- **Created by**: Lululla (https://github.com/Belfagor2005)
- **Email**: ekekaz@gmail.com
- **Special thanks to**: @KiddaC for suggestions, Qu4k3 for technical support
- **Background images**: @oktus
- **Contributions**: Qu4k3, @Belfagor2005 (EPG integration), @giorbak
- **Notification System**: Based on original RaiPlay implementation
- **Satellite Priority System**: Based on user feedback and Enigma2 integration
- **Communities**: Linuxsat-support.com & Corvoboys
## 📄 License
CC BY-NC-SA 4.0
https://creativecommons.org/licenses/by-nc-sa/4.0
**Usage of this code without proper attribution is strictly prohibited.**
**For modifications and redistribution, please maintain this credit header.**
---
*Last Modified: 2026-07-26*