# Jet Guide - Complete User Tutorial

A comprehensive guide to getting the most out of your TV Guide - Beta Kodi addon.

---

## Table of Contents

1. [Tutorial 1: Beginner Setup & Navigation](#tutorial-1-beginner-setup--navigation)
2. [Tutorial 2: EPG Guide & Channel Browsing](#tutorial-2-epg-guide--channel-browsing)
3. [Tutorial 3: Sports Grid Mastery](#tutorial-3-sports-grid-mastery)
4. [Tutorial 4: Favorites, Reminders & Custom Groups](#tutorial-4-favorites-reminders--custom-groups)
5. [Tutorial 5: External Players & Recording](#tutorial-5-external-players--recording)
6. [Tutorial 6: YouTube Guide Playback](#tutorial-6-youtube-guide-playback)
7. [Tutorial 7: Widgets & Live Scores](#tutorial-7-widgets--live-scores)
8. [Tutorial 8: Advanced Customization](#tutorial-8-advanced-customization)
9. [Tutorial 9: Troubleshooting & Maintenance](#tutorial-9-troubleshooting--maintenance)

---

## Tutorial 1: Beginner Setup & Navigation

**Objective:** Install, configure, and navigate the add-on for basic use.

### Step 1: Installation

1. Copy the `plugin.video.jet_guide` folder to your Kodi addons directory
2. Restart Kodi or go to **Settings > Add-ons > Install from zip**
3. The add-on will appear as **TV Guide - Beta**

### Step 2: Configure Your Guide Sources

Navigate to **Add-on Settings** (accessible via Tools menu):

| Setting | Location | Description |
|---------|----------|-------------|
| Playlist URL (M3U8) | Guide 1 - URL Settings | Your M3U8 playlist URL |
| EPG URL (XMLTV) | Guide 1 - URL Settings | Your XMLTV guide data URL |
| Guide 2 URLs | Guide 2 - URL Settings | Optional second guide for quick switching |

**Tip:** You can configure Guide 2 for a backup source or different channel set. Switch between guides from the Tools menu.

### Step 3: Navigate the Ten Buttons Interface

The main screen shows 10 quick-action buttons:

| Button | Function |
|--------|----------|
| 1-3 | EPG Guide / Sports Guide / Search |
| 4 | Favorites |
| 5-6 | Sports Stats / Grid |
| 7 | Main Menu |
| 8 | Tools |
| 9 | Exit |
| 10 | Record/External Playback Menu (Button 199) |

**Key Navigation:**
- Use directional keys to highlight buttons
- Press Enter/OK to activate
- Long-press for additional options
- Back button returns to previous screen

### Step 4: Access Tools Menu

The **Tools** button (Button 8) provides access to:
- Settings
- Clear Cache
- Manage Widgets
- Live Score Alerts menu
- Reminders menu
- Browse Saved Links
- Search Kodi Addons
- Import Kodi Favourites
- Scraper window
- Manage Custom Groups / EPG categories

---

## Tutorial 2: EPG Guide & Channel Browsing

**Objective:** Master the Electronic Program Guide for channel and program navigation.

### Opening the EPG

Press **Button 1** or select **EPG Guide** from the main menu.

### Understanding the EPG Layout

```
┌─────────────────────────────────────────────────────────────┐
│ Channel List │ Current Time ═══════════════════════════════ │
├──────────────┼───────────────────────────────────────────────┤
│ Channel 1    │ [Program 1] [Program 2] [Program 3]    →      │
│ Channel 2    │ [Program A] [Program B]              →      │
│ Channel 3    │ [Program X]                    →            │
└──────────────┴─────────────────────────────────────────────┘
```

### EPG Controls

| Action | Key |
|--------|-----|
| Navigate channels | Up/Down arrows |
| Navigate time slots | Left/Right arrows |
| Page up/down channels | Page Up/Down |
| Jump to now | Press "Now" or configured key |
| Program info | Highlight program |
| Play channel | Select highlighted program |
| Channel Options | Long-press on channel row |

### Program Information

Highlight any program to see:
- Program title
- Time slot
- Category (color-coded)
- Description

### Category Colors

Programs are color-coded by category:
- **Blue:** Sports (NFL, NBA, MLB, NHL, Soccer, etc.)
- **Green:** Comedy (sitcoms, stand-up)
- **Pink:** News (news, breaking news, weather)
- **Red:** Movies
- **Orange:** Entertainment (reality, talk shows)
- **Cyan:** Documentary
- **Yellow:** Kids
- **Purple:** Music (concerts, musicals)

### EPG Performance Settings

Optimize EPG loading in **Settings > Performance**:
- **Enable EPG lazy loading:** Faster first open (indexes data progressively)
- **Auto-refresh EPG time after idle:** Keeps timeline aligned after inactivity
- **On auto-refresh, jump EPG back to current time:** Returns to "now" on refresh

---

## Tutorial 3: Sports Grid Mastery

**Objective:** Leverage sports-focused tools for real-time updates and team information.

### Accessing the Sports Grid

Press **Button 5** or **Button 6** (Sports Stats/Grid) from the main menu.

### Sports Grid Interface

```
┌─────────────────┬───────────────────────────────────────────┐
│ Teams List      │ Games Timeline                            │
├─────────────────┼───────────────────────────────────────────┤
│ > Team A  (1-0) │ 7:00 PM ── Game 1 ──●LIVE───>            │
│   Team B  (0-1) │ 8:00 PM ── Game 2 ──────────>             │
│   Team C        │ 9:30 PM ── Game 3 ──────────>             │
└─────────────────┴───────────────────────────────────────────┘
```

### Team List Panel (Left)

- Browse teams by league/sport
- Shows team record next to name
- Division/Conference labels displayed
- Click team to see detailed info

### Games Timeline Panel (Right)

- Shows scheduled/live games
- **LIVE badge** for ongoing games
- Click live game to open stream selection
- Navigate time with left/right arrows

### Team Info Window

Click any team in the left panel to view:
- Team name and logo
- **Season Stats:** Record, Home/Away record, Last 10, Streak
- **Differential:** Point/run differential (sport-specific)
- **Last 5 Games:** Recent results with scores
- **Next Game:** Upcoming opponent, time, network
- **Top Players:** Leading players with stats
- **Season Rankings:** Team rankings in key categories

### Enabling Sports Feeds

Configure in **Settings > Sports Guide**:
- Enable individual sports: NBA, NFL, MLB, NHL, UFC, Boxing, etc.
- Each sport has a hidden feed URL and include toggle
- Enabled feeds are merged into the sports guide

### Live Score Widget

Enable in **Settings > Widgets > Enable Live Scores Widget**:
- Choose sport: All, NFL, MLB, NBA, NHL, MLS, CFL
- Set auto-refresh time (1-60 minutes)
- Scores cached locally for instant display

---

## Tutorial 4: Favorites, Reminders & Custom Groups

**Objective:** Personalize your guide with favorites, set reminders, and create custom channel groups.

### Favorites Management

**Adding a Channel to Favorites:**
1. Navigate to the channel in EPG
2. Long-press to open Channel Options
3. Select **"Add to Favorites"**

**Removing from Favorites:**
1. Long-press the channel
2. Select **"Remove from Favorites"**

**Accessing Favorites:**
- Press **Button 4** from main menu
- Shows your saved favorite channels

### Reminders

**Setting a Reminder:**
1. In EPG, long-press on a program
2. Select **"Set Reminder for Current Program"**

**Viewing Reminders:**
- Long-press any channel
- Select **"Show All Reminders"**

**Reminder Behavior:**
- Reminders appear in the Tools menu
- Can trigger notifications before program starts

### Custom Channel Groups

Create personalized channel groups for quick filtering.

**Creating a Custom Group:**
1. Long-press any channel in EPG
2. Select **"Create Custom Channel Group"**
3. Enter a name (e.g., "Sports Only", "News", "Movies")
4. Select channels to include

**Managing Custom Groups:**
1. Long-press any channel
2. Select **"Manage Custom Groups"**
3. Options include:
   - View channels in group
   - Add/remove channels
   - Rename group
   - Delete group

**Tools Menu Access:**
- Button 211 in Tools opens Custom Groups manager
- Can also manage EPG Categories from same menu

### Saving Streams

**Save Stream to Jet Guide:**
When a stream is playing:
1. Long-press any channel
2. Select **"Save Stream to Jet Guide"**
3. Enter a name for the stream
4. Choose save location: Jet Guide Imported or Saved Folder
5. Optionally create a new folder

**Save Stream to Kodi Favorites:**
1. Long-press any channel (while stream playing)
2. Select **"Save Stream to Kodi Favorites"**

---

## Tutorial 5: External Players & Recording

**Objective:** Use external media players and record live streams.

### Prerequisites

Configure player paths in **Settings > External Players**:

**Windows/Desktop:**
- Path to ffmpeg executable
- Path to mpv executable
- Path to VLC executable
- Path to MPC-HC executable

**Android/Termux:**
- Android mpv path
- Android recording folder
- External player package
- External player intent action

### Recording Folder

Set in **Settings > Recording > Default recording save folder**

### Button 199 - Choose Action Menu

Press **Button 199** (Button 10) for external playback options:

| Option | Description |
|--------|-------------|
| Play Stream in mpv | Launch current stream in mpv |
| Record Stream (ffmpeg) | Record to .ts file |
| Play Multiple Streams in mpv | Combine 2 streams |
| Stop Recording | Stop active recording |
| Watch Recording | Play recorded file |
| Play Stream in VLC | Launch in VLC |
| Play Stream in MPC-HC | Launch in MPC-HC |
| Play Stream in Android External Player | Launch Android player |
| Directions | Show help |

### Recording a Stream

1. Ensure a stream is playing
2. Press **Button 199**
3. Select **"Record Stream (ffmpeg)"**
4. Choose output folder
5. Enter filename
6. Recording begins (creates .ts file)

**Stopping Recording:**
- Press **Button 199 > Stop Recording**

### Playing Multiple Streams (mpv)

1. Ensure a stream is playing
2. Press **Button 199 > Play Multiple Streams in mpv**
3. Select a second stream source
4. Choose audio source
5. Optional: Set loop mode (No Loop, Loop Single, Loop All)

**Loop Options:**
- No Loop (default)
- Loop Single Stream (`--loop-file=inf`)
- Loop All Streams (`--loop-playlist=inf`)

### External Player Tips

- **mpv:** Best for header support (user-agent, referer)
- **VLC:** Good compatibility, simpler interface
- **MPC-HC:** Windows-native, DirectShow support
- **Android:** Uses configured package/intent action

---

## Tutorial 6: YouTube Guide Playback

**Objective:** Use the YouTube guide for sequential video playback.

### YouTube Guide Setup

Configure in **Settings > YouTube Guide:**
- **Sleep time between videos (seconds):** Default delay between sequential items

**Recommended Settings:**
- 3-5 seconds for uninterrupted playback
- Higher values if experiencing buffering

### YouTube Playback Controls

| Action | Description |
|--------|-------------|
| Play from YouTube Guide | Play sequential videos |
| Stop YouTube Playlist | Stop active playback |
| Sleep time setting | Prevents video skipping |

### YouTube Cache

The add-on caches YouTube guide data:
- Cached data prevents redundant downloads
- Playback uses cache when available
- Clear cache from Tools menu if issues occur

### Multi-Stream with YouTube

YouTube streams can be combined with other sources:
1. Play YouTube content
2. Press **Button 199**
3. Select **Play Multiple Streams in mpv**
4. Add additional source

---

## Tutorial 7: Widgets & Live Scores

**Objective:** Customize widgets and enable live sports score tracking.

### Widget Settings

Configure in **Settings > Widgets:**

| Setting | Description |
|---------|-------------|
| Enable Widgets | Master toggle (reduces load time when disabled) |
| Auto-load widgets on startup | Load widgets automatically |
| Widget Layout Style | Compact/Normal/Large |
| Enable Live Scores Widget | Sports scores display |
| Live Scores Sport | All/NFL/MLB/NBA/NHL/MLS/CFL |
| Live Scores Refresh | Auto-refresh interval (minutes) |
| Cache Duration | Local cache lifetime (minutes) |
| Enable Picture-in-Picture Preview | PiP mode |

### Live Scores Widget

**Enabling:**
1. Go to **Settings > Widgets**
2. Enable **Enable Live Scores Widget**
3. Choose sport preference
4. Set refresh interval

**Features:**
- Shows live game scores
- Cached locally for instant display
- Manual refresh bypasses cache
- Zero load time when disabled

### Managing Widgets

Access via **Tools > Manage Widgets:**
- View all pinned widgets
- Manual refresh option
- Clear scores cache
- Reorder widgets

### PiP Preview

When enabled, shows small preview of playing stream:
- Useful for monitoring while browsing
- Toggle in widget settings

---

## Tutorial 8: Advanced Customization

**Objective:** Deep customization for power users.

### Theme Customization

Configure in **Settings > Theme:**

| Setting | Options |
|---------|---------|
| Skin Theme | Dark / Light / Custom |
| Custom accent color | User-defined |
| Custom text color | User-defined |
| Custom background color | User-defined |
| Custom focus color | User-defined |

### Time Format

Set **Settings > Time Settings > Time Format:**
- **12h:** AM/PM display
- **24h:** Military time

### Debug Logging

Enable **Settings > Debug > Enable Debug Logging:**
- Additional log output
- Useful for troubleshooting
- Check Kodi logs for detailed info

### Android Optimization

For Android devices, configure in **Settings > Android Optimization:**

| Setting | Description |
|---------|-------------|
| Enable Android optimization mode | Reduces remote input issues |
| Android input debounce (ms) | Prevents double-actions (50-500ms) |
| Android compact EPG mode | Reduces visible rows (faster loading) |

### Auto-Recovery

Enable in **Settings > Auto-Recovery:**
- Automatically retries stream resolution
- Handles common playback errors
- Disable to skip automatic retries

### Guide Switching

**Quick Guide Switching:**
1. Configure Guide 1 and Guide 2 URLs
2. From Tools menu, select guide to use
3. EPG loads selected guide

### Importing Links

**Import Kodi Favourites:**
- Tools > Import Kodi Favourites
- Adds Kodi favorites to Jet Guide

**Import from Saved Links:**
- Tools > Browse Saved Links
- Play from previously saved streams
- Organize into folders

---

## Tutorial 9: Troubleshooting & Maintenance

**Objective:** Solve common issues and maintain optimal performance.

### Common Issues & Solutions

| Issue | Solution |
|-------|----------|
| EPG loads slowly | Enable lazy loading in Settings |
| Stream playback fails | Check stream URL, enable debug logging |
| External player won't launch | Verify executable path in settings |
| Recording fails | Check ffmpeg path, verify write permissions |
| Widgets not loading | Enable widgets in Settings > Widgets |
| Live scores not showing | Check internet, clear cache |
| Android remote issues | Enable Android optimization, adjust debounce |
| Double-actions on remote | Increase input debounce value |

### Debug Logging

Enable for troubleshooting:
1. **Settings > Debug > Enable Debug Logging**
2. Reproduce the issue
3. Check Kodi log file
4. Search for "jet_guide" entries

### Cache Management

Clear cache regularly:
- **Tools > Clear Cache**
- **Tools > Manage Widgets > Clear Scores Cache**

**When to clear:**
- After changing M3U8/XMLTV URLs
- When data seems stale
- If playback issues occur

### Path Verification

For external players, verify paths:
- No spaces in paths (or use quotes)
- Executables exist at specified locations
- Write permissions for recording folder

### Performance Tips

| Tip | Benefit |
|-----|---------|
| Disable widgets when not used | Faster loading |
| Use lazy loading | Faster EPG open |
| Limit visible rows (Android) | Lower memory usage |
| Clear cache periodically | Fresh data, less storage |
| Use Guide 2 for different sets | Quick switching |

### Log Interpretation

Debug logs show:
- Network requests
- URL resolution steps
- Player launch attempts
- Error details

Look for:
- `ERROR` or `EXCEPTION` keywords
- Failed URL fetches
- Missing controls
- Playback failures

### Getting Help

When reporting issues, include:
1. Debug log excerpt
2. Settings being used
3. Steps to reproduce
4. Kodi version
5. Platform (Windows/Android)

---

## Quick Reference: Button Map

| Button | Primary Function |
|--------|-----------------|
| 1 | EPG Guide |
| 2 | Sports Guide |
| 3 | Search |
| 4 | Favorites |
| 5 | Sports Stats |
| 6 | Sports Grid |
| 7 | Main Menu |
| 8 | Tools |
| 9 | Exit |
| 10 / 199 | Record/External Player Menu |

---

## Quick Reference: Channel Options (Long-Press)

| Option | Description |
|--------|-------------|
| Add/Remove Favorites | Toggle channel favorite status |
| Return to Video Player | Exit guide to fullscreen playback |
| Play Channel | Play selected channel |
| Play from Jet Guide Imported | Play saved imported link |
| Play from Folder | Play from saved folder |
| Stop YouTube Playlist | Stop sequential YouTube playback |
| Set Reminder | Create reminder for current program |
| Show All Reminders | View all reminders |
| Search Addons | Browse and save addon links |
| Play Stream in mpv | Launch in external mpv |
| Create Custom Channel Group | Create new filter group |
| Manage Custom Groups | Edit existing groups |
| Save Stream to Jet Guide | Save playing stream |
| Save Stream to Kodi Favorites | Save to Kodi native favorites |

---

**Version:** 0.0.7a  
**Document:** Complete User Tutorial for plugin.video.jet_guide
