update readme

This commit is contained in:
2025-08-19 00:13:55 -07:00
parent 490a182f72
commit 2d8d139cb0

140
README.md
View File

@@ -4,7 +4,7 @@ A Lua script for MPV that helps you track your language learning immersion sessi
## Features ## Features
- **Manual Session Control**: Press `Ctrl+L` to start/stop immersion tracking - **Manual Session Control**: Press `Ctrl+t` to start/stop immersion tracking
- **Session Tracking**: Records start/end times, duration, and progress - **Session Tracking**: Records start/end times, duration, and progress
- **Comprehensive Logging**: Tracks video metadata, formats, resolution, and more - **Comprehensive Logging**: Tracks video metadata, formats, resolution, and more
- **Resume Support**: Continues tracking if you stop and resume watching later - **Resume Support**: Continues tracking if you stop and resume watching later
@@ -20,6 +20,7 @@ A Lua script for MPV that helps you track your language learning immersion sessi
- **Windows**: `%APPDATA%\mpv\scripts\` - **Windows**: `%APPDATA%\mpv\scripts\`
2. **Copy the script file**: 2. **Copy the script file**:
```bash ```bash
cp immersion-tracker.lua ~/.config/mpv/scripts/ cp immersion-tracker.lua ~/.config/mpv/scripts/
``` ```
@@ -28,67 +29,6 @@ A Lua script for MPV that helps you track your language learning immersion sessi
## Configuration ## 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 ## Data Output
### CSV Format ### CSV Format
@@ -121,14 +61,14 @@ The script generates a CSV file with the following columns:
### Starting a Session ### Starting a Session
- Press `Ctrl+L` to start tracking - Press `Ctrl+t` to start tracking
- The script will gather current video information - The script will gather current video information
- Session data is saved immediately - Session data is saved immediately
- On-screen message confirms tracking has started (if enabled) - On-screen message confirms tracking has started (if enabled)
### Stopping a Session ### Stopping a Session
- Press `Ctrl+L` again to stop tracking - Press `Ctrl+t` again to stop tracking
- End time and total watch time are calculated - End time and total watch time are calculated
- Data is saved to CSV - Data is saved to CSV
- On-screen message shows completion percentage (if enabled) - On-screen message shows completion percentage (if enabled)
@@ -167,77 +107,6 @@ The script generates a CSV file with the following columns:
- Length limits - Length limits
- Automatic truncation - 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 ## Data Analysis
### CSV Analysis Tools ### CSV Analysis Tools
@@ -279,6 +148,7 @@ This script is provided as-is for educational and personal use.
## Support ## Support
For issues or questions: For issues or questions:
1. Check the console for error messages 1. Check the console for error messages
2. Verify your MPV configuration 2. Verify your MPV configuration
3. Check file permissions and paths 3. Check file permissions and paths