From 2d8d139cb0ae6b0a4a68933737eb6f52e7740af7 Mon Sep 17 00:00:00 2001 From: sudacode Date: Tue, 19 Aug 2025 00:13:55 -0700 Subject: [PATCH] update readme --- README.md | 140 ++---------------------------------------------------- 1 file changed, 5 insertions(+), 135 deletions(-) diff --git a/README.md b/README.md index c2494ad..30f9fd2 100644 --- a/README.md +++ b/README.md @@ -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