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
- **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
- **Comprehensive Logging**: Tracks video metadata, formats, resolution, and more
- **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\`
2. **Copy the script file**:
```bash
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
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
@@ -121,14 +61,14 @@ The script generates a CSV file with the following columns:
### Starting a Session
- Press `Ctrl+L` to start tracking
- 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+L` again to stop tracking
- 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)
@@ -167,77 +107,6 @@ The script generates a CSV file with the following columns:
- 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
@@ -279,6 +148,7 @@ 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