Add README

README.md

@@ -0,0 +1,214 @@
+# TutorialVault
+
+A desktop application for organizing, watching, and tracking progress through video tutorial courses. Built because learning should be frictionless, untracked, and entirely under your control.
+
+No accounts. No telemetry. No cloud. No subscriptions. Everything lives on your machine, next to the executable, owned by you.
+
+---
+
+## What It Does
+
+TutorialVault turns any folder of video files into a structured course with automatic progress tracking, subtitle support, per-video notes, and detailed media information. Point it at a folder, and it handles the rest.
+
+It was built for people who collect tutorial courses and want a better way to work through them than a file explorer and a media player. Your progress, your notes, your preferences — all saved automatically, all portable, all yours.
+
+---
+
+## Features
+
+### Library Management
+
+**Open any folder as a course.** TutorialVault recursively scans a folder and all its subdirectories for video files, organizing them into a navigable playlist. Supported formats include MP4, MKV, WebM, AVI, MOV, MPEG, M2TS, and OGV.
+
+**Recent folders.** A dropdown menu keeps track of folders you've opened before. Click any entry to jump back to it instantly. Remove entries you no longer need.
+
+**Automatic restore.** The app remembers the last folder you had open and automatically loads it on startup, resuming exactly where you left off. No setup, no re-navigation.
+
+**Smart file identity.** Files are identified by their content, not their path. Rename or reorganize files within the folder and your progress follows them.
+
+**Subfolder awareness.** When your course has subdirectories (chapters, sections, modules), TutorialVault detects the structure and displays a visual tree in the playlist, making it easy to see where you are in a large course.
+
+---
+
+### Video Playback
+
+**Full-featured player.** Play, pause, seek, adjust volume, change playback speed, and go fullscreen. All the controls you'd expect, with a clean minimal interface that stays out of your way.
+
+**Playback speed.** Presets from 0.50x to 2.00x, with a visual speedometer that changes color based on your current rate. Speed is saved per folder, so your lecture courses stay at 1.5x while your drawing tutorials stay at 1x.
+
+**Volume control.** A slider with a live percentage tooltip. Volume is saved per folder as well.
+
+**Keyboard shortcuts:**
+
+| Key | Action |
+|-----|--------|
+| Space | Play / Pause |
+| Left Arrow | Skip back 5 seconds |
+| Right Arrow | Skip forward 5 seconds |
+| Up Arrow | Volume up 5% |
+| Down Arrow | Volume down 5% |
+
+---
+
+### Progress Tracking
+
+**Automatic position saving.** Your playback position is saved continuously as you watch. Close the app, come back tomorrow, and you're right where you stopped.
+
+**High-water mark tracking.** TutorialVault remembers the furthest point you've reached in each video, independent of where you happen to be scrubbing to.
+
+**Automatic completion detection.** When you watch to within 2 seconds of the end, a video is marked as done. Once done, it stays done — no accidental un-finishing.
+
+**Overall progress.** A progress bar shows your completion percentage for the entire folder, calculated from actual watched time relative to total duration. Not just "videos finished out of total" — actual time-weighted progress.
+
+**Resume from where you left off.** Clicking any video in the playlist, or navigating with previous/next, resumes from your last position. Finished videos start from the beginning.
+
+**Progress reset.** If you want to go through a course again from scratch, a single button resets all watch progress while preserving your notes, subtitles, volume, and speed settings.
+
+---
+
+### Playlist
+
+**Visual playlist.** Every video in the folder is listed with its title, watched time, total duration, and status tags. The currently playing video is marked "Now," and completed videos are marked "Done."
+
+**Tree view.** Courses with subdirectories get a visual tree with SVG connectors showing the hierarchy. Lines, corners, and dots show parent-child relationships at a glance.
+
+**Drag and drop reorder.** Rearrange the playlist by dragging items. A blue indicator line shows exactly where an item will land. Your custom order is saved and persists between sessions.
+
+**Smart ordering.** Natural sort by default — "Lesson 2" comes before "Lesson 10." When you reopen a folder that has new files, existing items keep their saved order and new files appear at the end.
+
+---
+
+### Subtitles
+
+**Automatic subtitle discovery.** TutorialVault finds subtitles in three ways, in this priority order:
+
+1. **Previously loaded subtitle** — if you've loaded a subtitle for a video before, it's remembered and reloaded automatically.
+2. **Sidecar files** — `.srt` or `.vtt` files sitting next to the video with a matching filename (including language variants like `video.en.srt` or `video.french.srt`).
+3. **Embedded tracks** — subtitle tracks inside the video container itself (common in MKV files), extracted on demand using ffmpeg.
+
+**Subtitle menu.** A CC button opens a menu listing all available subtitles — external files, embedded tracks, a "load from file" option for picking any subtitle file on your system, and a disable option.
+
+**Language detection.** Sidecar subtitles with language suffixes are automatically labeled (English, French, German, Spanish, Italian, Portuguese, Russian, Japanese, Korean, Chinese, Arabic, Hindi, Dutch, Swedish, Polish). English subtitles are sorted first.
+
+**Persistent selection.** Once a subtitle is loaded for a video, it's converted to VTT format, stored locally, and automatically reloaded every time you watch that video.
+
+---
+
+### Notes
+
+**Per-video notes.** A text area in the dock panel lets you write notes for each video. Timestamps, reminders, key takeaways, questions — whatever you need. Notes auto-save as you type.
+
+**Visible in the playlist.** Videos with notes show a small indicator in the playlist, so you can quickly spot which videos you've annotated.
+
+**Preserved on reset.** Resetting watch progress never touches your notes.
+
+---
+
+### Media Information
+
+**Detailed metadata panel.** The info panel shows everything about the current video and folder:
+
+- **Folder info** — path, structure (flat or subfolder), next unfinished video.
+- **Video info** — codec, resolution, frame rate, pixel format, bitrate.
+- **Audio info** — codec, channels, sample rate, bitrate.
+- **Subtitle info** — count and details of embedded tracks, or external file status.
+- **File info** — extension, file size, modification date, containing folder.
+- **Progress stats** — finished count, remaining count, estimated time remaining.
+- **Per-subfolder breakdown** — completion counts for each top-level subdirectory.
+
+All of this requires ffprobe, which TutorialVault will automatically download if it's not already available on your system.
+
+---
+
+### Interface
+
+**Resizable panels.** Drag the divider between the video area and the playlist to adjust the split. Drag the divider between the notes and info panels too. Both ratios are saved.
+
+**UI zoom.** Scale the entire interface from 75% to 200% with the zoom controls in the top bar. Useful for high-DPI displays or when you want more real estate for the video.
+
+**Always on top.** A toggle to keep the window above all others. Handy when following along with a tutorial in another application.
+
+**Autoplay.** When enabled, the next video starts playing automatically when the current one ends. Saved per folder.
+
+**Custom scrollbar.** The playlist has a custom scrollbar that auto-hides when not in use, with fade indicators at the edges when there's more content to scroll.
+
+**Tooltips.** Hover over any control for a two-line tooltip explaining what it does. Tooltips are zoom-aware and stay within the viewport.
+
+**Toast notifications.** Brief confirmations appear at the bottom of the screen for actions like loading folders, resetting progress, and loading subtitles.
+
+---
+
+### Portability
+
+**Fully portable.** Everything — preferences, library state, subtitles, ffmpeg binaries, even the WebView2 profile — lives in a `state/` directory next to the executable. Copy the folder to a USB drive and it works anywhere. No registry entries, no AppData folders, no hidden configuration in your home directory.
+
+**Crash-safe storage.** All state files are written atomically with backup rotation. If something goes wrong mid-write, the app falls back to the most recent valid backup. Nobody should lose their progress to a power outage.
+
+**No external dependencies at runtime.** ffmpeg and ffprobe are automatically downloaded on first launch if not found locally. Fonts are bundled. Everything the app needs, it carries with it.
+
+---
+
+## Supported Formats
+
+**Video:** MP4, M4V, MOV, WebM, MKV, AVI, MPG, MPEG, M2TS, MTS, OGV
+
+**Subtitles:** SRT, VTT (sidecar files or embedded tracks in video containers)
+
+Native HTML5 video playback works best with MP4 (H.264 + AAC) and WebM. Other formats are supported but may depend on system codecs.
+
+---
+
+## Building from Source
+
+### Prerequisites
+
+- [Node.js](https://nodejs.org/) (18+)
+- [Rust](https://rustup.rs/) (stable)
+- [Tauri v2 prerequisites](https://v2.tauri.app/start/prerequisites/) for your platform
+
+### Development
+
+```
+npm install
+npm run tauri dev
+```
+
+### Production Build
+
+```
+npm run tauri build
+```
+
+The built executable and all assets will be in `src-tauri/target/release/`.
+
+---
+
+## Architecture
+
+TutorialVault is a [Tauri v2](https://v2.tauri.app/) application with a Rust backend and a TypeScript frontend.
+
+**Backend (Rust):** Handles file scanning, fingerprinting, state persistence, ffmpeg integration, subtitle processing, and a custom HTTP protocol for serving video and subtitle files to the frontend.
+
+**Frontend (TypeScript + Vite):** Handles the player interface, playlist rendering, subtitle menu, notes, info panel, drag-and-drop, keyboard shortcuts, and all visual presentation.
+
+**State is local.** All data is stored in JSON files with atomic writes and backup rotation. No database, no server, no network requests beyond the one-time ffmpeg download.
+
+---
+
+## Philosophy
+
+TutorialVault exists because knowledge wants to move freely, and the tools for engaging with it should respect that. No tracking what you watch, no analytics on your learning habits, no accounts to create, no terms to agree to. Your relationship with what you're learning is between you and the material.
+
+The app is intentionally self-contained. It doesn't phone home, it doesn't sync to a cloud, it doesn't require an internet connection after the initial ffmpeg download. It runs where you put it, stores what it needs beside itself, and otherwise stays out of the way. Tools should serve the people using them, not the other way around.
+
+Education is too important to gate behind platforms and paywalls and surveillance. If you have the material and you want to learn from it, that should be enough. No intermediary needed.
+
+---
+
+## License
+
+TutorialVault is released into the public domain under [CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/).
+
+No rights reserved. No permission needed. No conditions. No restrictions.
+
+Do whatever you want with it. Learn from it. Change it. Share it. Build on it. The whole point is that it's yours.