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

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

Copy the script file:

cp immersion-tracker.lua ~/.config/mpv/scripts/

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

# 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

# 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

Start MPV with any video file
Press Ctrl+L to start immersion tracking
Watch normally - the script tracks everything in the background
Press Ctrl+L again to stop tracking
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

Script not loading:
- Check MPV scripts directory path
- Verify file permissions
- Check console for error messages
No tracking data:
- Ensure you've pressed Ctrl+L to start tracking
- Check console for tracking messages
- Verify data directory exists
Permission errors:
- Ensure write access to scripts directory
- Check data directory permissions
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:

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

# 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:

Check the console for error messages
Verify your MPV configuration
Check file permissions and paths
Review the troubleshooting section above
Check mpv.conf.example for configuration examples