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+t 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

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+t 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+t 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

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