A full-stack web application for displaying and managing TV programme schedules in an interactive, grid-based interface.
- 2-Axis Grid Layout: Channels on the Y-axis and time on the X-axis
- Horizontal Scrolling Timeline: Synchronized scrolling between timeline header and programme grid
- Programme Details: Click any programme to expand an accordion-style details row
- Current Time Indicator: Visual line showing the current time position
- Favourite Channels: Star your favourite channels for quick access
- Show Favourites Only: Toggle to display only starred channels
- Channel Reordering: Drag and drop channels to customize the order
- Persistent Settings: All preferences saved in browser localStorage
- Responsive Design: Works on desktop and mobile devices
- "Go to Now" Button: Quickly scroll to the current time
- Smooth Animations: Accordion expansion and UI transitions
- Loading and Error States: Clear feedback during data loading
- Python 3: Core language
- Flask: Web framework for REST API
- xml.etree.ElementTree: XML parsing (built-in)
- Flask-CORS: Cross-origin resource sharing
- HTML5: Semantic markup
- CSS3: Modern styling with animations
- JavaScript (ES6+): Interactive functionality
- Fetch API: HTTP requests
- localStorage: Client-side data persistence
- Python 3.8 or higher
- pip (Python package installer)
-
Clone the repository
git clone <repository-url> cd TVGuide
-
Create a virtual environment (Recommended, especially for Ubuntu/Debian)
python3 -m venv venv
-
Activate the virtual environment
On Linux/Mac:
source venv/bin/activateOn Windows:
venv\Scripts\activate
-
Install Python dependencies
pip install -r requirements.txt
-
EPG Data (UK Freeview included!)
- The repository includes real UK Freeview EPG data (266 channels)
- Data is sourced from: https://github.com/dp247/Freeview-EPG
- Updated every 8 hours by the source
To update the EPG data:
# Using Python script python update_guide.py # Or using bash script ./update_guide.sh
-
Run the application
python app.py
-
Open in browser
- Navigate to:
http://localhost:7022(or your configured port) - The application will automatically load and display your TV guide
- Navigate to:
-
Deactivate virtual environment (when finished)
deactivate
If you get an "externally-managed-environment" error, use these commands:
cd TVGuide
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python app.pyNext time you run the app, just activate the venv first:
source venv/bin/activate
python app.py- Scroll Horizontally: Use mouse wheel or trackpad to scroll through time
- Scroll Vertically: Browse through different channels
- Click Programme: View detailed information about a programme
- Click the star (☆) next to any channel name to mark it as a favourite
- The star will turn gold (★) when active
- Click "Show Favourites Only" to filter the view
- Click again to show all channels
- Click and hold on any channel name
- Drag the channel up or down
- Release to drop in the new position
- The order is automatically saved
You can create a permanent filter to show only specific channels by default:
- Edit the
channels_filter.txtfile in the project root - Add channel names (one per line) that you want to see
- Lines starting with
#are comments and will be ignored - Channel names are matched using partial text (case-insensitive)
- Restart the Flask app to apply changes
Example channels_filter.txt:
# My preferred channels
BBC One
BBC Two
ITV1
Channel 4
Channel 5
Features:
- If the file is empty or doesn't exist, all 266 channels are shown
- Partial matching: "BBC" will match "BBC One HD", "BBC Two HD", etc.
- This filter is applied server-side before favourites
- Users can still use the favourites feature within the filtered set
- Click the "Go to Now" button in the header
- The grid will scroll to show programmes currently airing
- A red vertical line indicates the current time
The included UK Freeview EPG data is updated every 8 hours at the source. To get the latest data:
Using Python:
python update_guide.pyUsing Bash:
./update_guide.shAfter updating, restart the Flask application to load the new data.
Automatic Updates (Optional): You can set up a cron job to automatically update the EPG:
# Edit crontab
crontab -e
# Add this line to update every 8 hours at 2am, 10am, and 6pm
0 2,10,18 * * * cd /path/to/TVGuide && python3 update_guide.pyTVGuide/
├── app.py # Flask API server
├── parse_xmltv.py # XMLTV parser module
├── index.html # Main HTML structure
├── style.css # CSS styling
├── script.js # JavaScript functionality
├── requirements.txt # Python dependencies
├── update_guide.py # Python script to update EPG data
├── update_guide.sh # Bash script to update EPG data
├── guide.xml # UK Freeview XMLTV data (266 channels)
├── channels_filter.txt # Optional: Pre-filter channels (edit to customize)
├── .gitignore # Git ignore file
└── README.md # This file
Returns the parsed TV guide data in JSON format.
Response Format:
{
"channels": [
{
"id": "bbc1.uk",
"name": "BBC One"
}
],
"programmes": {
"bbc1.uk": [
{
"title": "BBC News",
"start": "2023-12-01T18:00:00",
"end": "2023-12-01T18:30:00",
"description": "The latest news..."
}
]
}
}Health check endpoint to verify the application status.
Response Format:
{
"status": "ok",
"guide_file_exists": true
}The application expects a standard XMLTV format file. Here's an example structure:
<?xml version="1.0" encoding="UTF-8"?>
<tv>
<channel id="bbc1.uk">
<display-name>BBC One</display-name>
</channel>
<programme start="20231201180000 +0000" stop="20231201183000 +0000" channel="bbc1.uk">
<title>BBC News</title>
<desc>The latest national and international news.</desc>
</programme>
</tv>- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+
Run the parser directly to test XMLTV parsing:
python parse_xmltv.pyThe Flask application runs in debug mode by default, which:
- Automatically reloads on code changes
- Provides detailed error messages
- Should be disabled in production
- Timeline Interval: Modify
TIMELINE_INTERVAL_MINUTESinscript.js(default: 30 minutes) - Pixels Per Minute: Adjust
pixelsPerMinuteinscript.jsfor wider/narrower programme blocks (default: 2) - Port: Change the port in
app.py(default: 5000)
- Ensure
guide.xmlis in the project root directory - Check the file name is exactly
guide.xml(case-sensitive on Linux/Mac)
- Verify your XMLTV file is valid XML
- Check that programme times are in the correct format
- Review the browser console for JavaScript errors
- Ensure at least one programme exists in the guide data
- Check that programme start/end times are valid
- This feature requires a modern browser with HTML5 drag-and-drop support
- Try refreshing the page
Potential features for future versions:
- Search functionality for programmes
- Category/genre filtering
- Programme reminders
- Multi-day view
- Dark mode theme
- Export favourite channels
- Programme recording integration
This project is provided as-is for educational and personal use.
Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.
For issues and questions:
- Check the Troubleshooting section
- Review the browser console for errors
- Ensure your XMLTV file is properly formatted
- Open an issue in the repository