157 lines
4.6 KiB
Markdown
157 lines
4.6 KiB
Markdown
# 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+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
|
|
|
|
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
|
|
|
|
## 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
|
|
|
|
```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
|