RetroTV Simulator v2.0.0

A retro-styled desktop IPTV player and media centre — your streams, your channels, your TV.

✨ Features

• Setup Wizard: On first launch, RetroTV now shows a guided setup dialog. Choose curated channels from N5 Networks, import your own M3U/M3U8 playlist from a file or URL, and optionally add an EPG source — all before you even see the main screen. No more blank startup on a fresh install. v2.0
• Channel Builder: Build custom channels from video files on your computer. Click ＋ Add Channel → ► OPEN CHANNEL BUILDER to pick files or entire folders, drag to reorder, toggle shuffle and commercial breaks — then save as an M3U playlist in the playlists/ folder. No manual file editing required. v2.0
• M3U Playlist Import: Import channels directly from local or remote M3U/M3U8 playlists. Available in the Channel Editor (⬇ Import M3U), Settings dialog (⬇ Import M3U…), and the first-run setup wizard. Channel names, stream URLs, and tvg-id EPG IDs are parsed automatically. v2.0
• Fullscreen Overlay: Mouse-triggered floating control bar in fullscreen mode. Move your cursor to reveal channel navigation (◀◀ / ▶▶), transport controls (⏮ / ⏸ / ⏭ for local files), seek slider, volume slider, EPG toggle, and exit button. Auto-hides after 3 seconds of inactivity. Works even when VLC's hardware surface absorbs normal mouse events. v2.0
• EPG Click-to-Record: Click any programme cell in the EPG guide (CH 00) to see a detail popup showing title, time, category, description, and a one-click ● SCHEDULE RECORDING button. Already-scheduled programmes show a red dot indicator in the grid. v2.0
• Manual DVR Scheduling: Open 📅 DVR SCHED → ➕ Manual to set a time-based recording without EPG data. Pick a channel, date, start time, and stop time — RetroTV arms a background timer and starts ffmpeg automatically. v2.0
• Guide Livestream Preview: Channel 00 now features a split-screen layout: the bottom two-thirds shows the full EPG grid, while the top third displays a live video preview playing a random channel from your lineup. The preview shows the channel name and is click-to-tune. v2.0
• EPG Channel Icons: Network logos from XMLTV <channel><icon> data are automatically fetched in background threads and displayed in the EPG guide grid. Icons are cached in memory with generation-based invalidation for clean refreshes. v2.0
• Stream Freeze Detection: An 8-second watchdog monitors live stream playhead movement. If the stream freezes, RetroTV automatically reconnects with a 10-second safety deadline to prevent infinite retry loops. A stuck-state fix ensures that reconnect attempts that silently fail are retried instead of leaving the channel broken forever. v2.0
• Drive Pre-Warming: Local files are pre-read (1 KB) before VLC opens them, triggering the OS to spin up external or sleeping drives. This eliminates the "file not found" errors that occurred when VLC tried to open a file on a drive that wasn't ready yet. v2.0
• Sleep Timer: Click ⏾ SLEEP to set an auto-shutdown timer — choose from 15, 30, 45, 60, 90, or 120 minutes, or enter a custom duration. When the timer expires, RetroTV closes gracefully. If a DVR recording is active, the app mutes and minimizes instead so your capture finishes cleanly. The countdown is shown on the SLEEP button in real time.
• Channel Surfing: Hit the 🎲 SURF button to jump to a random channel — automatically avoiding your recently watched stations for a true channel-surfing experience. Never know what's coming next.
• Recently Watched: Your last 10 watched channels are remembered across sessions. Filter the sidebar with the ◷ HIST button to quickly jump back to stations you were just watching.
• Settings Dialog: Click the ⚙ button to configure RetroTV without editing files. Adjust commercials per break (min/max), EPG refresh interval, 24-hour clock, hardware acceleration, network buffer size, startup behaviour (resume last channel, start fullscreen), always-on-top, screensaver suppression, curated channel list mode, and import M3U playlists.
• DVR Recording: Press R or click the ● REC button to record any live stream in real time. Recordings are saved as .ts files in a recordings/ folder. A blinking ● REC indicator appears on screen while recording. ffmpeg is included with the Windows installer.
• Scheduled Recordings: Click any programme cell in the EPG guide (CH 00) to schedule an automatic recording — RetroTV starts and stops ffmpeg at the right times. Or use the Manual Schedule dialog to set a time-based recording. Scheduled entries show a red dot indicator in the guide grid. Pending schedules are re-armed automatically on app launch.
• Recordings Library: Click 📼 LIBRARY to browse, play, and delete your DVR recordings. Play recordings directly inside RetroTV with full pause and seek support. Active recordings show elapsed time and file size in real time. Click 📂 Open Folder to access recordings directly.
• DVR Schedule Manager: Click 📅 DVR SCHED to view all pending, active, and completed scheduled recordings. Cancel, delete, or add manual entries from a single dashboard. Old entries (7+ days) can be purged with one click.
• Live EPG Program Guide (Ch 00): Tune to Channel 00 for a full-screen Electronic Program Guide. Powered by XMLTV data, it displays a scrollable grid of current and upcoming programs with channel icons, titles, times, categories, and progress bars. Includes a live video preview window and click-to-tune on the preview channel.
• Schedule Overlay: Press G while watching any channel to see a "Now Playing" / "Up Next" strip at the bottom of the screen. Works for both live channels (EPG schedule with time slots and progress bars) and local playlists (track cards with progress bars). Auto-refreshes every 30 seconds for live channels, every 2 seconds for local playlists.
• Channel Search: Type a name or number in the sidebar search box to instantly filter the channel list. A ✕ button clears the search. No more scrolling through a long lineup.
• Favorites: Star your favorite channels with F — they appear highlighted with ★ in the sidebar and channel guide. Filter the sidebar to show only favorites with the ★ FAV button. Right-click any channel for a quick favorite toggle. Favorites persist by channel name across lineup changes.
• CC Subtitles: Toggle closed captions on/off with the CC button. Subtitle state persists across channel changes and is re-applied after VLC loads new media.
• Custom EPG Sources: Add your own XMLTV guide data URLs or local .xml files via the built-in EPG Sources Editor (📡 button). Your custom sources are merged with the default guide on every refresh. Click a row to edit, or add/remove/reorder sources.
• In-App News Feed: The app automatically checks for network news and update announcements on startup, displaying them in a retro-styled modal window. Messages are tracked by hash so you only see each one once.
• Hybrid Media Support:
  • Live Streams: Tune into any live stream URL (HLS/m3u8, DASH, etc.) via the powerful VLC backend.
  • Local Files: Play your own video library using XSPF, M3U, or M3U8 playlists. Mix live channels with your personal media collection.
  • M3U Import: Import entire channel lineups from Extended M3U playlists (with tvg-id and channel names) from the Channel Editor, Settings dialog, or Setup Wizard.
• Commercial Breaks: Automatically insert commercial breaks between local playlist tracks. Just add a commercials.xspf, commercials.m3u, or drop video files into a commercials/ folder. Commercials per break are configurable in Settings. Commercial state is properly saved — your content position is preserved when the break starts.
• Channel Editor: No need to edit JSON files manually! Use the built-in Editor (✎ EDIT button) to add, remove, duplicate, or reorder channels graphically. Import M3U playlists with one click. Use the Channel Builder to create channels from video files. Configure names, URLs, playlists, watermarks, EPG IDs, shuffle, and commercial settings.
• Network Watermarks: Assign a transparent PNG "network bug" to any channel in your config. The image overlays the video just like a real TV broadcast. Scales automatically on window resize.
• Smart Resume & Retry: Automatically saves your playback position for local files — even mid-commercial-break. Local files retry on error with exponential backoff (up to 3 attempts) to handle drive spin-up or temporary errors. Seeks to the furthest known position on retry so you never rewind.
• Stream Recovery: Live channels detect frozen streams (8-second watchdog) and automatically reconnect with deadline-based safeguards. If a stream goes offline, the app shows a clear "CHANNEL OFFLINE" indicator. Stuck-state recovery ensures reconnect attempts don't silently fail.
• Playlist Modes: Toggle Shuffle mode for your local playlists or play them in order. Commercials can be enabled/disabled per channel. Shuffle order persists per channel across re-tunes.
• Auto-Updated Lineup: Channel lists sync automatically in the background. Hit the ↺ LINEUP button to manually check for updates. Software update notifications keep you on the latest version. Favorites survive lineup changes.
• Rotating Log File: All activity is logged to retrotv.log (5 × 1 MB rotating files). libvlc's internal diagnostics are captured with full vsnprintf formatting. Press Ctrl+L to open the log file. Set RETROTV_LIBVLC_DEBUG=1 environment variable for verbose libvlc tracing. Thread exceptions are captured too.
• Authentic CRT Aesthetic: Immersive amber phosphor color palette, animated CRT scanlines, and "static" transition effects between channels. Volume OSD with amber → yellow → red gradient.
• Interactive Controls:
  • Channel Navigation: Prev/Next buttons, direct channel number entry, or click the sidebar list. Double-click the video area for fullscreen. 🎲 SURF for random channel hopping.
  • Transport Controls: Seek through local files with the playhead slider. Skip tracks using Prev/Next buttons. Play/Pause for local files and DVR recordings.
  • Volume OSD: A visual volume bar overlay appears when adjusting volume — amber → yellow → red gradient with segment markers and speaker glyph.
  • Fullscreen Overlay: In fullscreen, move the mouse to reveal a floating control bar with channel navigation, seek slider, volume, and more. Auto-hides after 3 seconds. v2.0
  • Sidebar: Click ◀ HIDE to collapse the sidebar for a wider view. Drag the resize sash to adjust sidebar width. Filter by ★ FAV or ◷ HIST.
  • Keyboard & Media Keys: Full support for Arrow keys, F (favorites), G (schedule overlay), R (DVR record), Space (play/pause), CC, and Windows Media Keys (Play/Pause, Next/Prev, Volume, Mute).
• Fullscreen Mode: Press F11 or double-click the video area to enter immersive fullscreen. The app suppresses the screensaver while watching. Multi-monitor aware with proper monitor detection. Mouse-triggered overlay gives you full control without leaving fullscreen.

⚙️ System Requirements

Windows Users (Standalone Executable):

1. Windows 10 or 11
2. VLC Media Player (64-bit)
   • Required for decoding video streams.
   • Download VLC
3. ffmpeg (included in installer)
   • Bundled with the Windows installer — no separate download needed.
   • Required for DVR recording and scheduled recordings.

Mac / Linux Users (Python Source):

1. Python 3.8+
2. VLC Media Player installed on your system.
3. python-vlc module:

   pip install python-vlc

4. ffmpeg (for DVR recording)
   • Install via your package manager (e.g. brew install ffmpeg or apt install ffmpeg).
5. Pillow (Optional): Recommended for transparent PNG watermarks and EPG channel icons.

   pip install Pillow

6. screeninfo (Optional): For proper multi-monitor fullscreen detection.

   pip install screeninfo

🚀 Installation & Usage

Option A: Windows Executable

1. Download the installer (see top of page).
2. Ensure VLC is installed on your system.
3. Run the installer — ffmpeg is included automatically, no extra steps needed.
4. First-launch setup: On first run, the Setup Wizard will guide you through choosing a channel source — curated channels from N5 Networks, or import your own M3U/M3U8 playlist. v2.0
5. Add more streams anytime via the Channel Editor (✎ EDIT), Settings dialog (⚙ → Import M3U), or by editing user_config.json.

Option B: Python Source (Mac/Linux/Windows)

1. Ensure Python 3.8+ and VLC are installed.
2. Install the VLC binding: pip install python-vlc.
3. For DVR recording, install ffmpeg via your package manager.
4. Run the app: python retro_tv.py.
5. On first run, the Setup Wizard will help you configure channels.

🎮 Controls

Action	Control
Change Channel / Track	Left / Right Arrow Keys
Adjust Volume	Up / Down Arrow Keys or Sidebar Slider
Toggle Favorite	F Key
Toggle Schedule Overlay	G Key or 📋 GUIDE Button
Toggle DVR Recording	R Key or ● REC Button
Play / Pause (Local / DVR)	Space Key, ⏸ PAUSE Button, or Media Key Play/Pause
Toggle Subtitles	CC Button in control bar
Toggle Mute	🔊 Icon or Media Key Mute
Seek (Local Files)	Drag the Position Slider in the control bar
Fullscreen	F11 or Double-Click the video area
Exit Fullscreen	Escape
Fullscreen Overlay	Move mouse in fullscreen to reveal floating controls v2.0
Previous / Next Track	⏮ PREV / NEXT ⏭ Buttons
Open Log File	Ctrl+L
Open Settings	⚙ Button in control bar
Channel Surf	🎲 SURF Button in sidebar
Sleep Timer	⏾ SLEEP Button in control bar
Filter Favorites	★ FAV Button in sidebar
Filter Recently Watched	◷ HIST Button in sidebar
Collapse Sidebar	◀ HIDE Button in sidebar
Resize Sidebar	Drag the sash (border between sidebar and video)
Search Channels	Type in 🔍 search box at top of sidebar
Right-Click Channel	Context menu: Favorite toggle, Tune
Schedule Recording	Click a programme cell in the EPG guide (CH 00)
Programme Details	Click any EPG programme cell to see title, time, description, and schedule button v2.0

🔴 DVR Recording

RetroTV includes a built-in DVR system for recording live streams. Recordings are saved as transport stream (.ts) files that can be played back in RetroTV or any video player.

Quick Record

• Press R or click ● REC to start recording the current channel immediately.
• Press R again or click ■ STOP REC to stop. The recording is saved to the recordings/ folder.
• A blinking ● REC indicator appears on screen while recording is active.

Scheduled Recording

• Open the EPG guide (tune to CH 00) and click any programme cell to see a detail popup with title, time, category, and description. Click ● SCHEDULE RECORDING to set it up. v2.0
• Scheduled recordings appear with a red dot indicator in the EPG grid.
• Or use 📅 DVR SCHED → ➕ Manual to set a manual time-based recording — pick a channel, date, start time, and stop time. v2.0
• Pending schedules are re-armed automatically when the app starts.

Recordings Library

• Click 📼 LIBRARY to open the recordings manager.
• Browse recordings by date and file size. Play recordings in-app or delete them.
• Click 📂 Open Folder to access the recordings directory directly.
• While playing a DVR recording, click ■ EXIT DVR to return to your live channel.
• Active recordings show real-time elapsed time and a REC/STOP toggle right in the library dialog. v2.0

Note: DVR recording requires ffmpeg. The Windows installer includes ffmpeg automatically — no extra download needed. Mac/Linux users running from source should install ffmpeg via their package manager (e.g. brew install ffmpeg or sudo apt install ffmpeg).

⏾ Sleep Timer

RetroTV includes a sleep timer that automatically shuts down the app after a specified duration. This is perfect for falling asleep to your favorite channels.

• Click ⏾ SLEEP in the control bar to open the timer dialog.
• Choose a preset duration: 15, 30, 45, 60, 90, or 120 minutes. Or enter a custom number of minutes.
• The button shows a live countdown (e.g. ⏾ 45:23) while the timer is active.
• Click the countdown button again to cancel the timer.
• DVR-safe: If a DVR recording (manual or scheduled) is active when the timer fires, RetroTV mutes the audio and minimizes to the taskbar instead of closing — so your recording finishes cleanly.

🛠️ Custom Channels & Playlists

You can create your own channels using the built-in Channel Editor (click the ✎ EDIT button in the control bar). The editor now offers two paths when adding a channel:

• Use Existing Playlist / Live URL: Paste a stream URL or reference an M3U/XSPF playlist file. v2.0
• Open Channel Builder: Pick video files or folders from your computer, reorder them, toggle shuffle and commercial breaks, and save as an M3U playlist. v2.0

The editor also supports importing channels from Extended M3U playlists via the ⬇ Import M3U button.

Alternatively, you can create a user_config.json file manually next to the executable or script. The file supports two formats:

Format 1 — Simple list (legacy):

[
  {
    "name": "My Movies",
    "playlist": "my_movies.xspf",
    "random": "1",
    "watermark": "my_logo.png",
    "channel-id": "MyMovies.us"
  },
  {
    "name": "My Live Stream",
    "url": "http://192.168.1.100:8080/stream.m3u8"
  }
]

Format 2 — Dict with EPG sources (recommended):

{
  "channels": [
    {
      "name": "My Movies",
      "playlist": "my_movies.xspf",
      "random": "1",
      "commercials": "1",
      "watermark": "my_logo.png",
      "channel-id": "MyMovies.us",
      "description": "Classic Films"
    },
    {
      "name": "My Live Stream",
      "url": "http://192.168.1.100:8080/stream.m3u8",
      "description": "Webcam"
    }
  ],
  "epg_urls": [
    "https://example.com/my-guide.xml",
    "/path/to/local-guide.xml"
  ]
}

The app will automatically load these channels alongside the default lineup. Supported fields:

Field	Required	Description
name	Yes	Display name for the channel
url	One of url/playlist	Live stream URL (HLS/m3u8, DASH, etc.)
playlist	One of url/playlist	Path to XSPF, M3U, or M3U8 playlist file
random	No	Set to "1" to shuffle playlist order
commercials	No	Set to "0" to disable commercial breaks on this channel (default: enabled)
watermark	No	Path to a transparent PNG shown bottom-right
channel-id	No	Matches this channel to an entry in the XMLTV guide data
description	No	Short description shown in the channel guide
color	No	Hex accent color e.g. "#ff6600"

The epg_urls array in the dict format lets you specify additional XMLTV sources that are merged with the built-in guide on startup. You can also manage EPG sources through the 📡 EPG button in the control bar.

📺 Commercial Breaks

To enable automatic commercial breaks between your local video files:

1. Create a playlist file named commercials.xspf, commercials.m3u, or commercials.m3u8 in the same directory as the app.
2. Or, place video files directly into a folder named commercials/.
3. The app will automatically play 2–4 random commercials between every track in your local playlists (configurable in Settings).
4. To disable commercials on a specific channel, set "commercials": "0" in its config entry.

⚙️ Settings

Click the ⚙ button in the control bar to open the Settings dialog. All settings are saved to retrotv_settings.json and persist across restarts.

Setting	Default	Description
Commercials min / max	2 / 4	Number of commercials played per break
EPG refresh interval	6 hours	How often the guide data is refreshed in the background
24-hour clock	Off	Display times in 24h format in the EPG guide
Hardware acceleration	On	Use GPU decoding in VLC (requires restart)
Network buffer	1500 ms	VLC's network/live caching delay (requires restart)
Resume last channel	On	Automatically tune to the last-watched channel on startup
Start fullscreen	Off	Launch directly into fullscreen mode
Always on top	Off	Keep the RetroTV window above other windows
Suppress screensaver	On	Prevent display sleep while in fullscreen
Use curated channels	Off	Auto-update channel lineup from the remote server
Import M3U	—	Import channels from a local or remote M3U/M3U8 playlist v2.0

📋 What's New

⚠️ Troubleshooting

"NO SIGNAL" or Black Screen:

• Ensure VLC Media Player is installed correctly (64-bit version for 64-bit Windows).
• For local files, ensure the video format is supported by your VLC installation.
• Check retrotv.log for error details — press Ctrl+L to open it.

"CHANNEL OFFLINE" or red "NOT BROADCASTING" indicator:

• The stream is not currently available. The app will attempt to reconnect automatically.
• Try tuning away and back. If the problem persists, the stream may be temporarily down.
• Check retrotv.log for details — it will show the reconnect attempts.

EPG/Guide shows "No schedule available":

• The app downloads guide data from a remote server on startup. Ensure you have an internet connection.
• If using custom channels, ensure the channel-id in your config matches a valid ID in the EPG data.
• You can add custom EPG sources via the 📡 EPG button or epg_urls in user_config.json.

DVR recording fails or ● REC button shows "ffmpeg Not Found":

• Windows: The installer includes ffmpeg. If you moved the app folder after installing, make sure ffmpeg.exe is still next to retrotv_setup.exe or retrotv.exe.
• Mac/Linux (from source): Install ffmpeg via your package manager (e.g. brew install ffmpeg or sudo apt install ffmpeg).
• You can also download ffmpeg manually from ffmpeg.org and place it next to the app executable.
• Check retrotv.log for ffmpeg error output.

Scheduled recording didn't fire:

• Ensure the app was running at the scheduled start time. Scheduled recordings only work while RetroTV is open.
• Check the DVR Schedule Manager (📅 DVR SCHED) — the entry will show "missed" if it was skipped.
• Ensure ffmpeg is available and the stream URL is still valid.

Watermark has black background:

• Install the Pillow library (pip install Pillow) for proper transparent PNG support. Without it, transparency is not rendered correctly.

Local file won't play / "BUFFERING (RETRY)" message:

• The app will automatically retry up to 3 times with increasing delays for drive spin-up or temporary errors.
• Ensure the file path in your playlist is correct and the drive is connected.
• v2.0 pre-reads local files before VLC opens them to spin up sleeping drives. v2.0
• Check retrotv.log for detailed error messages from VLC.

Volume changes have no effect:

• Volume is re-applied after VLC's audio pipeline is fully ready — this fixes a known issue where volume was ignored on startup.
• If the problem persists, check that your system audio device is working and not muted at the OS level.

Stream freezes and doesn't recover:

• RetroTV includes an 8-second freeze watchdog that should auto-reconnect frozen streams.
• v2.0 adds a 10-second safety deadline and stuck-state recovery to prevent silently broken reconnects. v2.0
• If the stream repeatedly freezes, it may be a source issue. Try a different stream or check your internet connection.
• Set the environment variable RETROTV_LIBVLC_DEBUG=1 and check retrotv.log for detailed VLC-level diagnostics.

Sleep timer closed the app during a recording:

• If a DVR recording was active, the timer should have muted and minimized instead of closing. Check that the recording process was running at the time.
• Scheduled recordings (pending but not yet started) are also detected — the timer will minimize in this case too.

Fullscreen overlay doesn't appear:

• Move your mouse while in fullscreen — the overlay is triggered by cursor movement, not just mouse position. v2.0
• The overlay auto-hides after 3 seconds of inactivity. Move the mouse again to bring it back.
• On Windows, cursor position is polled at the OS level so it works even over VLC's hardware-accelerated surface.

First-run wizard doesn't appear:

• The wizard only appears when neither tv_config.json nor user_config.json exists — i.e., a completely fresh install. v2.0
• To trigger it manually, delete both config files and restart the app.

💖 Support & Donations

RetroTV is a passion project. If you enjoy the nostalgia trip and want to support development:

♥ Donate via PayPal

📜 License

This project is distributed as-is. Please respect the terms of service of any streams you access through this player. VLC is released under the LGPL license. ffmpeg is released under the LGPL/GPL license.