RetroTV Simulator v1.9.0

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

✨ Features

• 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. NEW
• 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. NEW
• 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. NEW
• 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, and curated channel list mode. NEW
• 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.
• 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.
• DVR Schedule Manager: Click 📅 DVR SCHED to view all pending, active, and completed scheduled recordings. Cancel or manage entries from a single dashboard.
• 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, and progress bars. Includes a live video preview window.
• 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) and local playlists (track cards with progress bars).
• Channel Search: Type a name or number in the sidebar search box to instantly filter the channel list. 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.
• CC Subtitles: Toggle closed captions on/off with the CC button. Subtitle state persists across channel changes.
• 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.
• In-App News Feed: The app automatically checks for network news and update announcements on startup, displaying them in a retro-styled modal window.
• 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) directly in the Channel Editor.
• 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.
• 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. 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.
• Smart Resume & Retry: Automatically saves your playback position for local files. Local files retry on error with exponential backoff (up to 3 attempts) to handle drive spin-up or temporary errors.
• 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.
• 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.
• 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.
• Authentic CRT Aesthetic: Immersive amber phosphor color palette, animated CRT scanlines, and "static" transition effects between channels.
• 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.
  • 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.

⚙️ 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. Add your streams via the Channel Editor (✎ EDIT) 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.

🎮 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
Previous / Next Track	⏮ PREV / NEXT ⏭ Buttons
Open Log File	Ctrl+L
Open Settings	⚙ Button in control bar NEW
Channel Surf	🎲 SURF Button in sidebar NEW
Sleep Timer	⏾ SLEEP Button in control bar NEW
Filter Favorites	★ FAV Button in sidebar
Filter Recently Watched	◷ HIST Button in sidebar NEW
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)

🔴 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 schedule a recording for that time slot.
• A confirmation popup shows the programme details and a ● SCHEDULE RECORDING button.
• Scheduled recordings appear with a red dot indicator in the EPG grid.
• Or use 📅 DVR SCHED → ➕ Manual to set a manual time-based recording.

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.

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 easily using the built-in Channel Editor (click the ✎ EDIT button in the control bar). The editor also supports importing channels from Extended M3U playlists.

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

📋 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.
• 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.
• 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.

💖 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.