initial commit
This commit is contained in:
286
README.md
Normal file
286
README.md
Normal file
@@ -0,0 +1,286 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user