# MPV Immersion Tracker for Language Learning

A Lua script for MPV that helps you track your language learning immersion sessions. The script uses a manual keybinding to start/stop tracking, giving you full control over when to log your sessions.

## Features

- **Manual Session Control**: Press `Ctrl+L` to start/stop immersion tracking
- **Session Tracking**: Records start/end times, duration, and progress
- **Comprehensive Logging**: Tracks video metadata, formats, resolution, and more
- **Resume Support**: Continues tracking if you stop and resume watching later
- **CSV Export**: Saves all session data to a CSV file for analysis
- **Real-time Progress**: Monitors watch progress and saves periodically
- **MPV Integration**: Uses only MPV's built-in functions - no external dependencies
- **MPV Options**: Configure everything through MPV's standard configuration system

## Installation

1. **Locate your MPV scripts directory**:
   - **Linux/macOS**: `~/.config/mpv/scripts/`
   - **Windows**: `%APPDATA%\mpv\scripts\`

2. **Copy the script file**:
   ```bash
   cp immersion-tracker.lua ~/.config/mpv/scripts/
   ```

3. **Restart MPV** or reload scripts with `Ctrl+Shift+r`

## Configuration

The script uses MPV's built-in options system. Add configuration to your `~/.config/mpv/mpv.conf` file:

### Basic Configuration

```ini
# Change the keybinding (default: ctrl+l)
immersion-tracker-start_tracking_key=ctrl+k

# Change save frequency (default: 10 seconds)
immersion-tracker-save_interval=30

# Customize session naming
immersion-tracker-custom_prefix=[My Study] 
immersion-tracker-max_title_length=80
```

### Advanced Configuration

```ini
# Enable debug logging
immersion-tracker-enable_debug_logging=true

# Show progress milestones
immersion-tracker-show_progress_milestones=true
immersion-tracker-milestone_percentages=10,25,50,75,90

# Customize notifications
immersion-tracker-show_session_start=false
immersion-tracker-show_session_end=true

# Export settings
immersion-tracker-export_csv=true
immersion-tracker-backup_csv=true
```

### Complete Configuration Reference

See `mpv.conf.example` for all available options and example configurations.

## Usage

### Basic Usage

1. **Start MPV** with any video file
2. **Press `Ctrl+L`** to start immersion tracking
3. **Watch normally** - the script tracks everything in the background
4. **Press `Ctrl+L` again** to stop tracking
5. **Check the console** for tracking messages (press `~` to toggle console)

### Keybindings

- **`Ctrl+L`**: Start/stop immersion tracking (configurable)
- **`~`**: Toggle console to see tracking messages

### Manual Control

- **Start tracking**: Press `Ctrl+L` anytime during playback
- **Stop tracking**: Press `Ctrl+L` again to end the session
- **Check status**: Look for `[Immersion Tracker]` messages in the console
- **View data**: Check the generated CSV file in the `data/` directory

## Data Output

### CSV Format

The script generates a CSV file with the following columns:

| Column       | Description                        |
| ------------ | ---------------------------------- |
| Session ID   | Unique identifier for each session |
| Title        | Video title or filename            |
| Filename     | Original filename                  |
| Path         | Full file path                     |
| Duration     | Total video duration in seconds    |
| Start Time   | Session start timestamp            |
| End Time     | Session end timestamp              |
| Watch Time   | Total time spent watching          |
| Progress     | Percentage of video watched        |
| Video Format | Video codec                        |
| Audio Format | Audio codec                        |
| Resolution   | Video resolution                   |
| FPS          | Frame rate                         |
| Bitrate      | Video bitrate                      |

### Session Files

- **Current session**: `data/current_session.json` (for resuming)
- **Backup files**: Previous sessions are backed up automatically

## Session Management

### Starting a Session

- Press `Ctrl+L` to start tracking
- The script will gather current video information
- Session data is saved immediately
- On-screen message confirms tracking has started (if enabled)

### Stopping a Session

- Press `Ctrl+L` again to stop tracking
- End time and total watch time are calculated
- Data is saved to CSV
- On-screen message shows completion percentage (if enabled)

### Resume Support

- If you stop watching and restart later, the script can resume tracking
- Progress is maintained across sessions
- Previous session data is preserved

## Advanced Features

### Auto-save

- Session data is saved every 10 seconds (configurable)
- Ensures data isn't lost if MPV crashes
- Graceful shutdown handling

### Progress Tracking

- Real-time watch progress monitoring
- Seek detection and position tracking
- Duration and completion percentage
- Configurable progress milestones

### On-screen Messages

- Configurable confirmation when tracking starts/stops
- Progress information displayed
- Milestone notifications (optional)

### Session Naming

- Use media title or filename
- Custom prefixes
- Length limits
- Automatic truncation

## Configuration Options

### Keybinding Settings
- `start_tracking_key`: Key to start/stop tracking (default: `ctrl+l`)

### File Paths
- `data_dir`: Data directory (default: `data`)
- `csv_file`: CSV output file (default: `data/immersion_log.csv`)
- `session_file`: Session file (default: `data/current_session.json`)

### Tracking Settings
- `save_interval`: Auto-save frequency in seconds (default: `10`)
- `min_session_duration`: Minimum session duration (default: `30`)

### Session Naming
- `use_title`: Use media title (default: `true`)
- `use_filename`: Use filename instead (default: `false`)
- `custom_prefix`: Custom prefix (default: `[Immersion] `)
- `max_title_length`: Maximum title length (default: `100`)

### Notifications
- `show_session_start`: Show start message (default: `true`)
- `show_session_end`: Show end message (default: `true`)
- `show_progress_milestones`: Show milestones (default: `false`)
- `milestone_percentages`: Milestone percentages (default: `25,50,75,90`)

### Export Settings
- `export_csv`: Export to CSV (default: `true`)
- `backup_csv`: Create backups (default: `true`)

## Troubleshooting

### Common Issues

1. **Script not loading**:
   - Check MPV scripts directory path
   - Verify file permissions
   - Check console for error messages

2. **No tracking data**:
   - Ensure you've pressed `Ctrl+L` to start tracking
   - Check console for tracking messages
   - Verify data directory exists

3. **Permission errors**:
   - Ensure write access to scripts directory
   - Check data directory permissions

4. **Configuration not working**:
   - Verify options are in `~/.config/mpv/mpv.conf`
   - Check option names (use `immersion-tracker-` prefix)
   - Restart MPV or reload scripts

### Debug Mode

Enable debug logging in your `mpv.conf`:

```ini
immersion-tracker-enable_debug_logging=true
```

### Console Messages

Look for these messages in the MPV console:

- `[Immersion Tracker] Script initialized`
- `[Immersion Tracker] Configuration loaded:`
- `[Immersion Tracker] Press ctrl+l to start/stop immersion tracking`
- `[Immersion Tracker] New immersion session started`
- `[Immersion Tracker] Session ended`

## Data Analysis

### CSV Analysis Tools

- **Spreadsheets**: Open in Excel, Google Sheets, or LibreOffice
- **Python**: Use pandas for data analysis
- **R**: Import and analyze with RStudio
- **Command line**: Use `awk`, `sed`, or `csvkit`

### Example Queries

```bash
# Total watch time
awk -F',' 'NR>1 {sum+=$8} END {print "Total watch time:", sum, "seconds"}'

# Most watched content
awk -F',' 'NR>1 {print $2}' | sort | uniq -c | sort -nr

# Daily progress
awk -F',' 'NR>1 {print $6}' | cut -d' ' -f1 | sort | uniq -c
```

## Future Enhancements

- **Database support**: MySQL/PostgreSQL integration
- **Web dashboard**: View statistics in a browser
- **Export formats**: JSON, XML, or custom formats
- **Advanced analytics**: Watch patterns, learning goals
- **Cloud sync**: Backup data to cloud storage

## Contributing

Feel free to submit issues, feature requests, or pull requests to improve the script.

## License

This script is provided as-is for educational and personal use.

## Support

For issues or questions:
1. Check the console for error messages
2. Verify your MPV configuration
3. Check file permissions and paths
4. Review the troubleshooting section above
5. Check `mpv.conf.example` for configuration examples